jamdesk 1.1.28 → 1.1.29

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.jamdesk.com">
-    <img src="https://www.jamdesk.com/logo-light.png" width="280" alt="Jamdesk" />
+    <img src="https://www.jamdesk.com/logo-universal.png" width="280" alt="Jamdesk" />
   </a>
 </p>
 
@@ -435,6 +435,7 @@ See the [docs.json reference](https://www.jamdesk.com/docs/config/docs-json-refe
 
 - Node.js v20.0.0+
 - npm v8+ (recommended)
+- macOS, Linux, or Windows (all tested in CI)
 
 ## Learn More
 
@@ -446,6 +447,7 @@ See the [docs.json reference](https://www.jamdesk.com/docs/config/docs-json-refe
 - [OpenAPI](https://www.jamdesk.com/docs/api-reference/openapi-setup)
 - [Deployment](https://www.jamdesk.com/docs/deploy)
 - [npm Package](https://www.npmjs.com/package/jamdesk)
+- [Release History](https://www.npmjs.com/package/jamdesk?activeTab=versions)
 - [Homepage](https://www.jamdesk.com)
 - [Pricing](https://www.jamdesk.com/pricing)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.28",
+  "version": "1.1.29",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/app/api/chat/[project]/route.ts

@@ -22,11 +22,14 @@
  */
 import { NextRequest } from 'next/server';
 import { querySimilarChunks } from '@/lib/vector-store';
-import { buildSystemPrompt, buildCannedIdentityReply, resolveSiteName } from '@/lib/chat-prompt';
+import { buildSystemPrompt, isCannedIdentityReply, resolveSiteName } from '@/lib/chat-prompt';
 import { getDocsPath, getBaseUrl, trackChatAnalytics } from '@/lib/route-helpers';
 import { getAnthropicClient } from '@/lib/anthropic-client';
+import { rewriteQueryForSearch } from '@/lib/query-rewriter';
 import { fetchDocsConfig } from '@/lib/r2-content';
 import { redis } from '@/lib/redis';
+import { CHAT_TOOLS } from '@/lib/chat-tools';
+import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
 export const maxDuration = 30;
@@ -37,113 +40,6 @@ const RATE_WINDOW_SECONDS = 60;
 const MAX_HISTORY = 10;
 const VALID_ROLES = new Set<string>(['user', 'assistant']);
 
-/**
- * Extract citations from Claude's response by matching [Title] references
- * against the vector search chunks. Deduplicates by page slug.
- * Falls back to top 2 unique pages by score if Claude didn't cite anything.
- */
-type Citation = { title: string; slug: string; section?: string };
-type ScoredChunk = { pageSlug: string; pageTitle: string; sectionHeading: string; score: number };
-
-function extractCitations(
-  responseText: string,
-  chunks: ScoredChunk[],
-): { sources: Citation[]; hadExplicitCitations: boolean } {
-  // Match [Title] but not markdown links [text](url)
-  const referencedTitles = new Set(
-    Array.from(responseText.matchAll(/\[([^\]]+)\](?!\()/g), (m) => m[1]),
-  );
-
-  const seen = new Set<string>();
-  const sources: Citation[] = [];
-
-  function addUniqueChunk(c: (typeof chunks)[number]): void {
-    if (seen.has(c.pageSlug)) return;
-    seen.add(c.pageSlug);
-    sources.push({ title: c.pageTitle, slug: c.pageSlug, section: c.sectionHeading });
-  }
-
-  // Filter chunks to only those Claude referenced, deduplicate by slug
-  for (const c of chunks) {
-    if (referencedTitles.has(c.pageTitle)) addUniqueChunk(c);
-  }
-
-  // Record whether Claude explicitly cited sources before the fallback
-  const hadExplicitCitations = sources.length > 0;
-
-  // Fallback: if Claude didn't cite anything explicitly, show top 2 unique pages by score
-  if (sources.length === 0) {
-    for (const c of chunks) {
-      addUniqueChunk(c);
-      if (sources.length >= 2) break;
-    }
-  }
-
-  return { sources, hadExplicitCitations };
-}
-
-/**
- * Detect option lists in Claude's response that indicate a clarification question.
- * Returns extracted option strings, or null if the response is a normal answer.
- *
- * Heuristic guards to avoid false positives on instructional lists:
- * - Response must contain a question mark or colon (clarification Qs ask something)
- * - Response must be short (< 500 chars — clarification Qs are brief)
- * - Must be 2-3 items (instructional lists tend to be longer)
- * - List must be at the END of the response
- *
- * Supports numbered (1. 2. 3.) and unnumbered (plain lines) formats.
- * Strips markdown formatting (bold, backticks) from option text.
- */
-export function extractClarificationOptions(responseText: string): string[] | null {
-  // Trim trailing whitespace/newlines so the $ anchor in option-list regexes
-  // matches reliably — SSE text deltas can include trailing newlines.
-  const text = responseText.trimEnd();
-
-  // Must indicate a question. A `?` always qualifies. A `:` only qualifies when
-  // the preamble contains clarification words (to avoid false positives on
-  // instructional lists like "To enable dark mode:\n\n1. Open Settings").
-  const hasQuestion = text.includes('?');
-  const hasClarificationColon = !hasQuestion
-    && text.includes(':')
-    && /\b(which|what|clarify|interested|looking for|asking|type of|kind of)\b/i.test(text);
-  if (!hasQuestion && !hasClarificationColon) return null;
-
-  // Only short responses are likely clarification questions
-  if (text.length > 500) return null;
-
-  // Strip markdown formatting (bold, italic, backticks) from option labels
-  function cleanOption(text: string): string {
-    return text.trim().replace(/[*`]/g, '');
-  }
-
-  // Primary: numbered list (1. 2. 3.) at the end
-  const numbered = text.match(
-    /\n\n1\.\s+(.+)\n2\.\s+(.+)(?:\n3\.\s+(.+))?$/,
-  );
-  if (numbered) {
-    const options = [cleanOption(numbered[1]), cleanOption(numbered[2])];
-    if (numbered[3]) options.push(cleanOption(numbered[3]));
-    return options;
-  }
-
-  // Fallback: unnumbered list (2-3 short lines at the end, after a blank line)
-  // Each line must be short (< 80 chars) and non-empty to distinguish from paragraphs
-  const unnumbered = text.match(
-    /\n\n([^\n]{2,80})\n([^\n]{2,80})(?:\n([^\n]{2,80}))?$/,
-  );
-  if (unnumbered) {
-    // Extra guard: lines must NOT look like sentences (no periods at end)
-    const lines = [unnumbered[1], unnumbered[2], unnumbered[3]].filter(Boolean) as string[];
-    const looksLikeOptions = lines.every(l => !l.trim().endsWith('.') && l.trim().length < 80);
-    if (looksLikeOptions && lines.length >= 2) {
-      return lines.map(cleanOption);
-    }
-  }
-
-  return null;
-}
-
 export async function POST(
   request: NextRequest,
   context: { params: Promise<{ project: string }> },
@@ -221,9 +117,34 @@ export async function POST(
     fetchDocsConfig(project).catch(() => null),
   ]);
 
-  let chunks: Awaited<ReturnType<typeof querySimilarChunks>>;
+  // Fully parallel retrieval:
+  //   - Original vector query runs immediately.
+  //   - Rewriter + rewritten-query vector search are chained into ONE promise,
+  //     then Promise.all'd with the original. Critical path is
+  //     max(original_query_time, rewriter_time + rewritten_query_time), not
+  //     max(original, rewriter) + rewritten_query_time.
+  // Any failure in the rewrite path resolves to an empty chunk list — the
+  // original query still returns results so chat doesn't fail.
+  const originalQueryPromise = querySimilarChunks(project, searchQuery, 15);
+
+  const rewrittenPathPromise: Promise<Awaited<ReturnType<typeof querySimilarChunks>>> =
+    rewriteQueryForSearch(message, history)
+      .catch(() => null)
+      .then(rewritten => {
+        // Compare against `message` (the rewriter's input), not `searchQuery`
+        // (which is enriched with prior-turn context for short follow-ups).
+        // The rewriter only sees `message`, so a no-op rewrite equals `message`.
+        if (!rewritten || rewritten === message) return [];
+        return querySimilarChunks(project, rewritten, 15).catch(() => []);
+      });
+
+  let originalChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
+  let rewrittenChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
   try {
-    chunks = await querySimilarChunks(project, searchQuery, 8);
+    [originalChunks, rewrittenChunks] = await Promise.all([
+      originalQueryPromise,
+      rewrittenPathPromise,
+    ]);
   } catch {
     return Response.json(
       { error: 'AI chat is not available for this project.' },
@@ -231,6 +152,21 @@ export async function POST(
     );
   }
 
+  // Merge: original chunks first (they match the user's literal phrasing),
+  // then unique chunks from the rewritten query. Dedup by pageSlug +
+  // sectionHeading — chunks with the same identity are interchangeable across
+  // queries.
+  const seenKeys = new Set(originalChunks.map(c => `${c.pageSlug}#${c.sectionHeading}`));
+  const chunks = [
+    ...originalChunks,
+    ...rewrittenChunks.filter(c => {
+      const key = `${c.pageSlug}#${c.sectionHeading}`;
+      if (seenKeys.has(key)) return false;
+      seenKeys.add(key);
+      return true;
+    }),
+  ];
+
   if (chunks.length === 0) {
     return Response.json(
       { error: 'No documentation content found for this project.' },
@@ -257,6 +193,8 @@ export async function POST(
     max_tokens: 2048,
     temperature: 0.3,
     system: systemPrompt,
+    tools: CHAT_TOOLS,
+    tool_choice: { type: 'any' },
     messages: [
       ...history.slice(-MAX_HISTORY),
       { role: 'user', content: message },
@@ -268,43 +206,127 @@ export async function POST(
     return encoder.encode(`data: ${JSON.stringify(data)}\n\n`);
   }
 
+  type Citation = { title: string; slug: string; section?: string };
+  type AnswerInput = { markdown?: string; cited_page_slugs?: string[] };
+  type ClarificationInput = { question?: string; options?: string[] };
+
+  function topChunksAsCitations(limit = 2, skip?: Set<string>): Citation[] {
+    const out: Citation[] = [];
+    const seen = new Set<string>(skip);
+    for (const c of chunks) {
+      if (seen.has(c.pageSlug)) continue;
+      seen.add(c.pageSlug);
+      out.push({ title: c.pageTitle, slug: c.pageSlug, section: c.sectionHeading });
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+
   const readable = new ReadableStream({
     async start(controller) {
-      let fullText = '';
+      let toolName: string | null = null;
+      let emittedMarkdownLength = 0;
+      let emittedQuestionLength = 0;
+
+      stream.on('inputJson', (_partialJson, jsonSnapshot) => {
+        if (!jsonSnapshot || typeof jsonSnapshot !== 'object') return;
+
+        // Gate on toolName — emitting before content_block_start resolves
+        // would leak clarification JSON into the answer text channel.
+        if (toolName === 'answer') {
+          const snap = jsonSnapshot as AnswerInput;
+          if (typeof snap.markdown === 'string' && snap.markdown.length > emittedMarkdownLength) {
+            const newContent = snap.markdown.slice(emittedMarkdownLength);
+            emittedMarkdownLength = snap.markdown.length;
+            controller.enqueue(sendEvent({ type: 'text', content: newContent }));
+          }
+        } else if (toolName === 'ask_clarification') {
+          const snap = jsonSnapshot as ClarificationInput;
+          if (typeof snap.question === 'string' && snap.question.length > emittedQuestionLength) {
+            const newContent = snap.question.slice(emittedQuestionLength);
+            emittedQuestionLength = snap.question.length;
+            controller.enqueue(sendEvent({ type: 'text', content: newContent }));
+          }
+        }
+      });
 
       try {
+        // Watch for content_block_start to learn which tool Claude picked.
         for await (const event of stream) {
-          if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
-            fullText += event.delta.text;
-            controller.enqueue(sendEvent({ type: 'text', content: event.delta.text }));
+          if (event.type === 'content_block_start' && event.content_block.type === 'tool_use') {
+            toolName = event.content_block.name;
           }
         }
 
-        // After streaming completes, get token usage
         const finalMessage = await stream.finalMessage();
         const inputTokens = finalMessage.usage?.input_tokens ?? 0;
         const outputTokens = finalMessage.usage?.output_tokens ?? 0;
 
-        // Extract clarification options (if Claude asked a disambiguation question)
-        const options = extractClarificationOptions(fullText);
-        if (options) {
+        // With tool_choice: 'any' there is exactly one tool_use block.
+        const toolUse = finalMessage.content.find(c => c.type === 'tool_use');
+        if (!toolUse || toolUse.type !== 'tool_use') {
+          throw new Error('Expected tool_use block in final message');
+        }
+
+        let sources: Citation[];
+        let hadExplicitCitations: boolean;
+        const hasClarification = toolUse.name === 'ask_clarification';
+
+        if (toolUse.name === 'answer') {
+          const input = toolUse.input as AnswerInput;
+          const slugs = Array.isArray(input.cited_page_slugs) ? input.cited_page_slugs : [];
+          const markdownText = typeof input.markdown === 'string' ? input.markdown : '';
+          // Suppress citations on the canned identity reply — otherwise the
+          // top-2 fallback would attach unrelated docs under "I'm the
+          // documentation assistant for …".
+          const isIdentityReply = isCannedIdentityReply(markdownText, siteName);
+
+          const seen = new Set<string>();
+          const explicitSources: Citation[] = [];
+          if (!isIdentityReply) {
+            for (const slug of slugs) {
+              const chunk = chunks.find(c => c.pageSlug === slug);
+              if (chunk && !seen.has(chunk.pageSlug)) {
+                seen.add(chunk.pageSlug);
+                explicitSources.push({
+                  title: chunk.pageTitle,
+                  slug: chunk.pageSlug,
+                  section: chunk.sectionHeading,
+                });
+              }
+            }
+          }
+          // Identity replies set hadExplicitCitations=true to mark intentional
+          // no-cite; non-identity answers fall back to top-2 when Claude omits slugs.
+          hadExplicitCitations = isIdentityReply || explicitSources.length > 0;
+          sources = isIdentityReply
+            ? []
+            : explicitSources.length > 0
+              ? explicitSources
+              : topChunksAsCitations(2, seen);
+        } else if (toolUse.name === 'ask_clarification') {
+          const input = toolUse.input as ClarificationInput;
+          const options = Array.isArray(input.options) ? input.options : [];
+          const question = typeof input.question === 'string' ? input.question.trim() : '';
+          // Missing question → UI shows buttons with no prompt.
+          // <2 options → dead-end UI. Interrupt so the user can retry.
+          if (!question) {
+            throw new Error('ask_clarification returned no question');
+          }
+          if (options.length < 2) {
+            throw new Error(`ask_clarification returned ${options.length} options; minimum is 2`);
+          }
           controller.enqueue(sendEvent({ type: 'clarification', options }));
+          // Surface top chunks so users see where the disambiguation candidates come from.
+          sources = topChunksAsCitations();
+          hadExplicitCitations = false;
+        } else {
+          throw new Error(`Unexpected tool name: ${toolUse.name}`);
         }
 
-        // Extract [Title] references from Claude's response (skip markdown links [text](url))
-        const { sources, hadExplicitCitations } = extractCitations(fullText, chunks);
-
-        // If Claude returned the canned identity reply, suppress citations — otherwise
-        // the "top 2 by score" fallback in extractCitations would attach unrelated
-        // docs sources under "I'm the documentation assistant for …".
-        const isIdentityReply = fullText.trim() === buildCannedIdentityReply(siteName);
-        controller.enqueue(sendEvent({
-          type: 'citations',
-          sources: isIdentityReply ? [] : sources,
-        }));
+        controller.enqueue(sendEvent({ type: 'citations', sources }));
         controller.enqueue(sendEvent({ type: 'done' }));
 
-        // Fire-and-forget analytics — only on success (finalMessage unreliable on error)
         trackChatAnalytics({
           projectSlug: project,
           query: message,
@@ -312,12 +334,17 @@ export async function POST(
           inputTokens,
           outputTokens,
           model: CHAT_MODEL,
-          hadExplicitCitations: isIdentityReply || hadExplicitCitations,
-          hasClarification: options !== null,
+          hadExplicitCitations,
+          hasClarification,
           durationMs: Date.now() - startTime,
           userAgent: request.headers.get('user-agent') || undefined,
         }).catch(() => {});
-      } catch {
+      } catch (err) {
+        log('warn', 'chat: stream interrupted', {
+          projectSlug: project,
+          toolName,
+          error: err instanceof Error ? err.message : String(err),
+        });
         controller.enqueue(sendEvent({ type: 'error', message: 'The response was interrupted. Please try again.' }));
       }
       controller.close();

package/vendored/components/chat/ChatEmptyState.tsx

@@ -5,6 +5,9 @@ import { memo, useMemo, useState, useCallback } from 'react';
 interface ChatEmptyStateProps {
   starterQuestions?: string[];
   onSelectQuestion: (question: string) => void;
+  /** Escape-hatch to hand the visitor off to Crisp. Omit to hide the button
+   *  (e.g. when Crisp isn't loaded). Detection happens in ChatPanel. */
+  onTalkToHuman?: () => void;
 }
 
 const STARTER_BASE = 'w-full text-left px-4 py-3 rounded-xl border text-sm transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]';
@@ -25,7 +28,7 @@ function starterButtonClass(question: string, selectedQuestion: string | null):
  * Starter questions are auto-generated by Haiku during builds when not
  * defined in docs.json — see lib/generate-starter-questions.ts.
  */
-export const ChatEmptyState = memo(function ChatEmptyState({ starterQuestions, onSelectQuestion }: ChatEmptyStateProps) {
+export const ChatEmptyState = memo(function ChatEmptyState({ starterQuestions, onSelectQuestion, onTalkToHuman }: ChatEmptyStateProps) {
   const shortcutKey = useMemo(
     () => typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent) ? '⌘' : 'Ctrl+',
     [],
@@ -74,6 +77,15 @@ export const ChatEmptyState = memo(function ChatEmptyState({ starterQuestions, o
           ))}
         </div>
       )}
+      {onTalkToHuman && (
+        <button
+          type="button"
+          onClick={onTalkToHuman}
+          className="mt-6 text-xs text-[var(--color-text-secondary)] hover:text-[var(--color-accent)] transition-colors cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)] rounded-md"
+        >
+          Need to talk to a human? <span className="font-medium text-[var(--color-accent)]">Start a chat →</span>
+        </button>
+      )}
     </div>
   );
 });

package/vendored/components/chat/ChatPanel.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import { useRef, useEffect, useLayoutEffect, useCallback } from 'react';
+import { useRef, useEffect, useLayoutEffect, useCallback, useState } from 'react';
 import { useChat } from '@/hooks/useChat';
 import { useBodyScrollLock } from '@/hooks/useBodyScrollLock';
 import { ChatMessage } from './ChatMessage';
 import { ChatInput } from './ChatInput';
 import { ChatEmptyState } from './ChatEmptyState';
+import { crispAvailable, hideCrispLauncher, openCrispChat, showCrispLauncher } from '../../lib/crisp-bridge';
 
 const SOMETHING_ELSE_PATTERNS = ['something else', 'none of the above', 'none of these'];
 
@@ -41,6 +42,15 @@ interface ChatPanelProps {
  */
 export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mode = 'overlay' }: ChatPanelProps) {
   const { messages, sendMessage, isLoading, abort, retry, clearChat, error, markClarificationSelected } = useChat(chatEndpoint);
+
+  const [hasCrisp, setHasCrisp] = useState(false);
+  useEffect(() => { setHasCrisp(crispAvailable()); }, []);
+
+  const handleTalkToHuman = useCallback(() => {
+    onClose();
+    openCrispChat();
+  }, [onClose]);
+
   const messagesContainerRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLDivElement>(null);
   const overlayPanelRef = useRef<HTMLDivElement>(null);
@@ -50,6 +60,17 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
   // Lock body scroll when mobile overlay is open
   useBodyScrollLock(!isInline && isOpen);
 
+  // Coordinate visibility with Crisp so the two chats don't overlap in the
+  // bottom-right corner. Applies to both modes — Crisp's fixed launcher sits
+  // behind the inline chat column's send button on desktop too.
+  useEffect(() => {
+    if (!isOpen) return;
+    hideCrispLauncher();
+    return () => {
+      showCrispLauncher();
+    };
+  }, [isOpen]);
+
   // On iOS, the virtual keyboard doesn't resize the layout viewport, so the
   // panel's max-h-[80dvh] can extend behind the keyboard. When the user taps the
   // textarea, iOS scrolls the page to reveal it — pushing the fixed panel off-screen.
@@ -171,6 +192,7 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
           <ChatEmptyState
             starterQuestions={starterQuestions}
             onSelectQuestion={sendMessage}
+            onTalkToHuman={hasCrisp ? handleTalkToHuman : undefined}
           />
         )}
       </div>
@@ -181,12 +203,24 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
           <p className="text-xs text-red-600 dark:text-red-400">
             {error}
           </p>
-          <button
-            onClick={retry}
-            className="text-xs font-medium text-red-600 dark:text-red-400 hover:underline flex-shrink-0 cursor-pointer"
-          >
-            Try again
-          </button>
+          <div className="flex items-center gap-3 flex-shrink-0">
+            {hasCrisp && (
+              <button
+                type="button"
+                onClick={handleTalkToHuman}
+                className="text-xs font-medium text-red-600 dark:text-red-400 hover:underline cursor-pointer"
+              >
+                Talk to a human
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={retry}
+              className="text-xs font-medium text-red-600 dark:text-red-400 hover:underline cursor-pointer"
+            >
+              Try again
+            </button>
+          </div>
         </div>
       )}
 
@@ -220,7 +254,7 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
       {/* Mobile backdrop (<lg) */}
       {isOpen && (
         <div
-          className="fixed inset-0 bg-black/50 backdrop-blur-sm z-[54] lg:hidden"
+          className="fixed inset-0 bg-black/50 backdrop-blur-sm z-[1000003] lg:hidden"
           onClick={onClose}
           aria-hidden="true"
         />
@@ -236,7 +270,7 @@ export function ChatPanel({ isOpen, onClose, starterQuestions, chatEndpoint, mod
         data-open={isOpen}
         data-chat-panel
         className={`
-          fixed z-[55] flex flex-col overflow-hidden
+          fixed z-[1000004] flex flex-col overflow-hidden
           transition-all duration-200
           inset-x-2 top-4 max-h-[80dvh] rounded-2xl shadow-xl border border-[var(--color-border)]
           lg:inset-x-auto lg:top-0 lg:max-h-none lg:rounded-none lg:shadow-none lg:border-0

package/vendored/lib/chat-prompt.ts

@@ -29,6 +29,40 @@ export function buildCannedIdentityReply(projectName: string): string {
   return `I'm the documentation assistant for ${projectName}, here to help with questions about the product.`;
 }
 
+/**
+ * Detects whether Claude's markdown output is the canned identity reply.
+ *
+ * Haiku at temperature 0.3 drifts the exact string in small ways: curly vs
+ * straight apostrophes, trailing period variants, surrounding markdown
+ * emphasis (`*...*`), or extra whitespace. An exact === compare against
+ * buildCannedIdentityReply would miss those and let the "top 2 by score"
+ * citation fallback attach unrelated docs sources under the identity reply.
+ *
+ * We normalize both sides (strip markdown emphasis/quotes, collapse
+ * whitespace, fold apostrophes, drop trailing punctuation, lowercase) and
+ * compare on the stable prefix "I'm the documentation assistant for <name>".
+ * A suffix check keeps the match anchored so arbitrary Haiku output that
+ * happens to start with that prefix while discussing something else doesn't
+ * slip through.
+ */
+export function isCannedIdentityReply(markdown: string, projectName: string): boolean {
+  if (!projectName) return false;
+  const canned = buildCannedIdentityReply(projectName);
+  const normalize = (s: string) =>
+    s
+      .replace(/&apos;|&#39;/g, "'")
+      .replace(/&quot;|&#34;/g, '"')
+      .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+      .replace(/[\u201C\u201D]/g, '"')
+      .replace(/[*_`>]/g, '')
+      .replace(/(?:^|\s)-{3,}(?:\s|$)/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .replace(/[.!?]+$/, '')
+      .toLowerCase();
+  return normalize(markdown) === normalize(canned);
+}
+
 /**
  * Produce the display name for the chat assistant's system prompt from a
  * docs.json config. Strips newlines and caps length to defend against
@@ -41,45 +75,49 @@ export function resolveSiteName(config: { name?: unknown } | null | undefined):
   return cleaned || DEFAULT_SITE_NAME;
 }
 
+/**
+ * Returns the system prompt as an array of text blocks. The first block
+ * contains ONLY the static instructions (identical for every request on the
+ * same project). The second block contains the dynamic, per-query context.
+ *
+ * Splitting by staticness means future prompt caching (out of scope for this
+ * plan) can be enabled by adding `cache_control: { type: 'ephemeral' }` to
+ * the first block only — a one-line change.
+ */
 export function buildSystemPrompt(
   projectName: string,
   chunks: ChatContext[],
   baseUrl: string,
   docsPath: string,
-): string {
-  const context = chunks.map((c, i) =>
-    `[Source ${i + 1}: ${c.pageTitle} > ${c.sectionHeading}](${baseUrl}${docsPath}/${c.pageSlug})\n${c.content}`
-  ).join('\n\n---\n\n');
-
-  return `You are a documentation assistant for ${projectName}. Answer the user's question using only the documentation context below.
+): Array<{ type: 'text'; text: string }> {
+  const staticRules = `You are a helpful documentation assistant for ${projectName}.
+Answer questions using ONLY the documentation context provided. If the answer is not in the context, call the \`answer\` tool with "I don't have information about that in the documentation." and cited_page_slugs: [].
 
 Rules:
 - IDENTITY (highest priority, overrides all other rules): If the user asks what you are, who made you, which model or AI powers you, or any variation (examples: "what model are you", "which AI is this", "are you Claude", "are you GPT", "who built you", "what are you running on"), respond with ONLY this exact sentence and nothing else: "I'm the documentation assistant for ${projectName}, here to help with questions about the product." Never mention Claude, Anthropic, OpenAI, GPT, Haiku, Sonnet, Opus, or any model or provider name when describing yourself or what powers you. You MAY mention these names when they appear in the documentation context and the user is asking about them as a subject (e.g., "how do I call the Claude API?" when Claude is documented) — in that case, answer normally using the context. Do not confirm or deny specific technologies about yourself. If the user presses or rephrases an identity question, repeat the canned sentence verbatim. If the user asks a compound question that mixes identity with a real doc question (e.g., "what model are you and how do I install?"), answer with ONLY the canned sentence — the identity clause wins.
-- Every response must start with the substantive answer. If the context addresses the question — including with "no", "not supported", or "you must do X yourself" — that IS the answer; state it directly and cite the source. Never open with a disclaimer like "I don't have information…", "The documentation doesn't cover that", or "According to the documentation".
-- If the context contains no information relevant to the topic, start with a brief lead-in like "${projectName} doesn't document that directly — here's the closest I found:" and describe what's available. Do not invent details.
-- Be concise and direct
-- Use markdown formatting, including code blocks with language hints when showing code
-- Cite sources by referencing the page title in brackets, e.g. [Getting Started]
-- Never make up information not in the context
-- Refer to this site as "${projectName}" or just "the documentation". Never expose internal project slugs, repo names, or hostnames (e.g. do not say "jamdesk-docs", "acme-docs", or "<slug>.jamdesk.app") even if they appear in source URLs
-- DISAMBIGUATION (highest priority, overrides the "start with the substantive answer" rule): If the context contains multiple distinct features or topics that could match the user's question (e.g., "Post Analytics" vs "Link Analytics" when asked about "analytics"), you MUST ask which one first — even if the user also asked for code examples or details. Your ENTIRE response must follow this EXACT format — nothing else:
+- Be concise and direct.
+- Use markdown formatting, including code blocks with language hints when showing code.
+- Never make up information not in the context.
+- Never combine "I don't have information" with a follow-up suggestion in the same response — that creates a self-contradiction. Pick one of exactly two response shapes:
+  (a) If any page in the Documentation context is relevant to the question, answer by referring to that page with a link (e.g., "See [Changelog](.../changelog) for recent releases."). Do not prefix with "I don't have information".
+  (b) If no relevant page is in context, respond with ONLY "I don't have information about that in the documentation." — no "but check", no "you can find", no alternatives.
+- Never name a page ("the Changelog", "the API reference", "the Settings page", etc.) unless that page appears in the Documentation context below.
+- Refer to this site as "${projectName}" or just "the documentation". Never expose internal project slugs, repo names, or hostnames (e.g. do not say "jamdesk-docs", "acme-docs", or "<slug>.jamdesk.app") even if they appear in source URLs.
+- When the context includes API endpoints (e.g. "POST /analytics/post") or technical operations, proactively include a short code example showing the request (HTTP method, endpoint, JSON body) even if the user didn't explicitly ask. If the context has no code-relevant information, skip the example.
+- Use the pageSlug values (shown in the context as [pageSlug: ...]) when populating cited_page_slugs — not the page title.
 
-<question ending with ?>
+Tool choice:
+- Use the \`answer\` tool for most questions.
+- Use the \`ask_clarification\` tool ONLY when the context contains 2-3 distinct, unrelated features that could match the user's question (e.g. "Post Analytics" vs "Link Analytics" when asked about "analytics"). If you are sure which one the user means, answer directly.`;
 
-1. <option>
-2. <option>
-3. <option>
-
-Rules: question mark required, numbered list required (1. 2. 3.), no descriptions after options, no extra text before or after. Example:
-
-Which type of analytics are you interested in?
+  const context = chunks.map((c) =>
+    `[pageSlug: ${c.pageSlug}] ${c.pageTitle} > ${c.sectionHeading}\nURL: ${baseUrl}${docsPath}/${c.pageSlug}\n${c.content}`,
+  ).join('\n\n---\n\n');
 
-1. Post Analytics
-2. Social Analytics
-3. Link Analytics
-- When the context includes API endpoints (e.g. "POST /analytics/post") or technical operations, proactively include a short code example showing the request (HTTP method, endpoint, JSON body) even if the user didn't explicitly ask for one. Technical users expect to see code. If the context has no code-relevant information, skip the example.
-- When constructing code examples from API endpoints in the context, use the endpoint, HTTP method, and any parameters/body fields mentioned. Always note it's a basic example and link to the full API reference page.
+  const dynamicContext = `Documentation context:\n${context}`;
 
-Documentation context:
-${context}`;
+  return [
+    { type: 'text', text: staticRules },
+    { type: 'text', text: dynamicContext },
+  ];
 }