jamdesk 1.1.27 → 1.1.29

package/vendored/lib/chat-prompt.ts

@@ -14,43 +14,110 @@ export interface ChatContext {
   score: number;
 }
 
+export const DEFAULT_SITE_NAME = 'this site';
+const MAX_SITE_NAME_LEN = 200;
+
+/**
+ * The exact sentence Claude must return when asked self-identity questions
+ * ("which model are you", "are you Claude", etc.). Exported so the chat route
+ * can detect identity responses and suppress unrelated RAG citations.
+ *
+ * Pinned by a unit test against the string embedded in buildSystemPrompt — if
+ * this helper drifts, citation suppression silently stops working.
+ */
+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
+ * prompt-injection via a malicious/misconfigured name. Falls back to a
+ * generic phrasing when the config is missing or has no usable name.
+ */
+export function resolveSiteName(config: { name?: unknown } | null | undefined): string {
+  if (!config || typeof config.name !== 'string') return DEFAULT_SITE_NAME;
+  const cleaned = config.name.replace(/[\r\n]+/g, ' ').trim().slice(0, MAX_SITE_NAME_LEN);
+  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 helpful documentation assistant for ${projectName}.
-Answer questions using ONLY the documentation context below. If the answer is not in the context, say "I don't have information about that in the documentation."
+): 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:
-- 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]
-- If unsure, say so rather than guessing
-- Never make up information not in the context
-- DISAMBIGUATION (highest priority): 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:
+- 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.
+- 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 },
+  ];
 }

package/vendored/lib/chat-tools.ts

@@ -0,0 +1,111 @@
+/**
+ * Tool schemas for the AI documentation chat.
+ *
+ * Forces Claude into structured output: it must call exactly one of
+ * `answer` (for direct answers) or `ask_clarification` (when the query
+ * matches 2-3 distinct topics in the retrieved context).
+ *
+ * Replaces the regex-based `extractCitations` and `extractClarificationOptions`
+ * parsers. Citations become the `cited_page_slugs[]` field on the answer tool;
+ * clarification options become the `options[]` field on the clarification tool.
+ */
+import type Anthropic from '@anthropic-ai/sdk';
+
+// Stricter local shapes so tests + consumers get typed access to nested
+// schema fields. The SDK types `input_schema.properties` as `unknown | null`,
+// which would force `any` casts at every access site. These local types are
+// structurally assignable to `Anthropic.Tool`, so they remain valid SDK input.
+interface AnswerToolSchema {
+  name: 'answer';
+  description: string;
+  input_schema: {
+    type: 'object';
+    properties: {
+      markdown: { type: 'string'; description: string };
+      cited_page_slugs: {
+        type: 'array';
+        items: { type: 'string' };
+        description: string;
+      };
+    };
+    required: ['markdown', 'cited_page_slugs'];
+  };
+}
+
+interface ClarificationToolSchema {
+  name: 'ask_clarification';
+  description: string;
+  input_schema: {
+    type: 'object';
+    properties: {
+      question: { type: 'string'; description: string };
+      options: {
+        type: 'array';
+        items: { type: 'string' };
+        minItems: 2;
+        maxItems: 3;
+        description: string;
+      };
+    };
+    required: ['question', 'options'];
+  };
+}
+
+export const ANSWER_TOOL: AnswerToolSchema = {
+  name: 'answer',
+  description:
+    'Provide a direct answer to the user\'s question using the documentation context. ' +
+    'Always populate cited_page_slugs with the pageSlug of every source you referenced. ' +
+    'If the context does not contain an answer, still call this tool and say "I don\'t have information about that in the documentation." with cited_page_slugs: [].',
+  input_schema: {
+    type: 'object',
+    properties: {
+      markdown: {
+        type: 'string',
+        description:
+          'The answer in markdown. Use code blocks with language hints when showing code. ' +
+          'Do not embed citation text like "[Page Title]" — citations are listed in cited_page_slugs.',
+      },
+      cited_page_slugs: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'The pageSlug values (e.g. "getting-started", "api/auth") for every documentation source you referenced. ' +
+          'Empty array if the answer is "I don\'t have information about that".',
+      },
+    },
+    required: ['markdown', 'cited_page_slugs'],
+  },
+};
+
+export const CLARIFICATION_TOOL: ClarificationToolSchema = {
+  name: 'ask_clarification',
+  description:
+    'Ask the user to choose between 2-3 distinct topics when their question is ambiguous. ' +
+    'Only use when the documentation context contains multiple unrelated features that could match ' +
+    '(e.g. "Post Analytics" vs "Link Analytics" when asked about "analytics"). ' +
+    'The question must end with a question mark.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      question: {
+        type: 'string',
+        description: 'A short disambiguation question ending with "?". E.g. "Which type of analytics are you asking about?"',
+      },
+      // minItems/maxItems are advisory to the model — Anthropic does NOT
+      // enforce them server-side. The chat route must defensively validate
+      // options.length before rendering a clarification UI.
+      options: {
+        type: 'array',
+        items: { type: 'string' },
+        minItems: 2,
+        maxItems: 3,
+        description: 'The distinct topics the user can choose between. Short labels like "Post Analytics", "Link Analytics".',
+      },
+    },
+    required: ['question', 'options'],
+  },
+};
+
+// Exported as Anthropic.Tool[] so it passes directly to client.messages.stream({ tools: CHAT_TOOLS }).
+export const CHAT_TOOLS: Anthropic.Tool[] = [ANSWER_TOOL, CLARIFICATION_TOOL];

package/vendored/lib/crisp-bridge.ts

@@ -0,0 +1,91 @@
+/**
+ * Bridge to the Crisp chat widget's command queue API.
+ *
+ * Coordinates visibility between our AI chat panel and Crisp's launcher
+ * so they don't visually collide in the bottom-right corner of docs sites.
+ *
+ * Crisp's docs: https://help.crisp.chat/en/article/how-to-use-crisp-from-javascript-api-1xhvaxt/
+ */
+
+type CrispAction = 'chat:close' | 'chat:hide' | 'chat:show' | 'chat:open';
+type CrispCommand = ['do', CrispAction];
+
+interface CrispQueue {
+  push(command: CrispCommand): void;
+}
+
+function getCrisp(): CrispQueue | null {
+  if (typeof window === 'undefined') return null;
+  const q = (window as unknown as { $crisp?: unknown }).$crisp;
+  if (q && typeof (q as { push?: unknown }).push === 'function') {
+    return q as CrispQueue;
+  }
+  return null;
+}
+
+export function crispAvailable(): boolean {
+  return getCrisp() !== null;
+}
+
+const RETRY_INTERVAL_MS = 500;
+const RETRY_MAX_ATTEMPTS = 30;
+
+let pendingHideTimer: ReturnType<typeof setInterval> | null = null;
+
+function clearPendingHideRetry(): void {
+  if (pendingHideTimer !== null) {
+    clearInterval(pendingHideTimer);
+    pendingHideTimer = null;
+  }
+}
+
+function applyHide(crisp: CrispQueue): void {
+  // chat:close must come before chat:hide. Crisp can auto-reshow the
+  // launcher after a session reset, so closing any open session first
+  // reduces the race window.
+  crisp.push(['do', 'chat:close']);
+  crisp.push(['do', 'chat:hide']);
+}
+
+export function hideCrispLauncher(): void {
+  if (typeof window === 'undefined') return;
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (crisp) {
+    applyHide(crisp);
+    return;
+  }
+  let attempts = 0;
+  pendingHideTimer = setInterval(() => {
+    attempts += 1;
+    const q = getCrisp();
+    if (q) {
+      applyHide(q);
+      clearPendingHideRetry();
+      return;
+    }
+    if (attempts >= RETRY_MAX_ATTEMPTS) {
+      clearPendingHideRetry();
+    }
+  }, RETRY_INTERVAL_MS);
+}
+
+export function showCrispLauncher(): void {
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (!crisp) return;
+  crisp.push(['do', 'chat:show']);
+}
+
+export function openCrispChat(): void {
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (!crisp) return;
+  crisp.push(['do', 'chat:show']);
+  crisp.push(['do', 'chat:open']);
+}
+
+// Test-only: clears module-level retry state between cases.
+export function _resetForTests(): void {
+  clearPendingHideRetry();
+}

package/vendored/lib/embedding-chunker.ts

@@ -14,8 +14,15 @@ export interface EmbeddingChunk {
   pageSlug: string;
   /** Heading of the section this chunk belongs to */
   sectionHeading: string;
-  /** Plain text content, stripped of markdown and JSX */
+  /** Plain-text body, stripped of markdown and JSX. Used for display (LLM context, search snippets). */
   content: string;
+  /**
+   * `<pageTitle> > <sectionHeading>\n` breadcrumb (plus `API Reference — METHOD /path\n`
+   * for API pages) that gets prepended to `content` when embedding — so BM25 finds
+   * chunks by page-title terms even when the body never uses them. Kept as a
+   * separate field so snippet consumers don't have to strip it.
+   */
+  prefix: string;
   /** Page title from frontmatter, or slug-derived fallback */
   pageTitle: string;
 }
@@ -111,18 +118,82 @@ function titleFromSlug(slug: string): string {
 }
 
 /**
- * Detect if a page is an API reference page and return a prefix label.
- * API pages get a prefix like "API Reference — POST /post\n" so the
- * embedding model clusters them distinctly from guides/tutorials.
+ * Build the per-chunk prefix that gets prepended to the cleaned content
+ * before embedding/upsert. Two purposes:
+ *
+ * 1. Title-breadcrumb: `<pageTitle> > <sectionHeading>` gives every chunk
+ *    a literal occurrence of its page title in the indexed text — so BM25
+ *    finds e.g. the `Changelog > April 2026` chunk for a "changelog" query
+ *    even when the month's content (Password Protection, YouTube Shorts)
+ *    never mentions the word "changelog" itself. Without this, pages that
+ *    happen to discuss a concept frequently (like `components/update`
+ *    documenting the `<Update>` MDX tag) outrank the actual answer chunks.
+ *
+ * 2. API-method tag: API-reference pages additionally get an
+ *    `API Reference — POST /endpoint` line so HTTP-method-specific queries
+ *    ("how do I POST to /analytics") cluster to the right endpoint page.
+ *
+ * Both lines end in `\n` so they stay visually separated from the content
+ * body when the chat model reads the full context block.
  */
 function getEmbeddingPrefix(
+  pageTitle: string,
+  sectionHeading: string,
   slug: string,
   frontmatter: Record<string, unknown>,
 ): string {
   const apiMethod = (frontmatter.api as string) || (frontmatter.openapi as string);
-  if (apiMethod) return `API Reference — ${apiMethod}\n`;
-  if (slug.startsWith('apis/')) return 'API Reference\n';
-  return '';
+  const apiLabel = apiMethod
+    ? `API Reference — ${apiMethod}\n`
+    : slug.startsWith('apis/') ? 'API Reference\n' : '';
+  const titleLabel = sectionHeading ? `${pageTitle} > ${sectionHeading}` : pageTitle;
+  return `${apiLabel}${titleLabel}\n`;
+}
+
+/**
+ * Without this, changelog-style pages that use `<Update>` wrappers (a
+ * Mintlify convention) collapse into a single heading-less blob — features
+ * in April get merged with features in March, and retrieval can't target
+ * a specific release. Promoting each label to a synthetic `### <label>`
+ * heading lets the existing heading splitter separate them.
+ *
+ * Matches `label` regardless of attribute order, handles self-closing tags,
+ * and leaves Update tags without a `label` attribute alone for
+ * `stripForEmbedding` to handle.
+ *
+ * Fenced code blocks are masked so Update tags inside ``` ... ``` examples
+ * (e.g. `components/update.mdx` pages that document the component itself)
+ * don't produce spurious chunks. `[^><]*?` (not `[^>]*?`) prevents a
+ * malformed opener (missing `>`) from greedily matching through to the
+ * next `</Update>` and silently eating body text.
+ */
+function preprocessUpdateBlocks(content: string): string {
+  const preserved: string[] = [];
+  const masked = content.replace(/```[\s\S]*?```/g, (m) => {
+    preserved.push(m);
+    return `\x00${preserved.length - 1}\x00`;
+  });
+
+  const transformed = masked
+    .replace(
+      /<Update\b[^><]*?\blabel="([^"]+)"[^><]*?\/?>/g,
+      (_, label: string) => {
+        const clean = sanitizeHeadingText(label);
+        return clean ? `\n### ${clean}\n` : '\n';
+      },
+    )
+    .replace(/<\/Update>/g, '\n');
+
+  return transformed.replace(/\x00(\d+)\x00/g, (_, i) => preserved[parseInt(i)]);
+}
+
+/**
+ * Collapse whitespace and drop leading `#` runs so a synthetic heading
+ * derived from a label (or a page title flowing into the breadcrumb) can't
+ * inject extra markdown heading depth or span multiple lines.
+ */
+function sanitizeHeadingText(raw: string): string {
+  return raw.replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
 }
 
 /**
@@ -137,11 +208,11 @@ export function chunkPageForEmbedding(
   maxChars = 2000,
 ): EmbeddingChunk[] {
   const slug = page.path.replace(/\.mdx?$/, '').replace(/\\/g, '/');
-  const pageTitle = (page.frontmatter.title as string) || titleFromSlug(slug);
-  const embeddingPrefix = getEmbeddingPrefix(slug, page.frontmatter);
+  const rawTitle = (page.frontmatter.title as string) || titleFromSlug(slug);
+  const pageTitle = sanitizeHeadingText(rawTitle) || titleFromSlug(slug);
 
   // Normalize Windows line endings before extracting sections
-  const normalizedContent = page.content.replace(/\r\n/g, '\n');
+  const normalizedContent = preprocessUpdateBlocks(page.content.replace(/\r\n/g, '\n'));
 
   const sections = extractSections(normalizedContent);
   const chunks: EmbeddingChunk[] = [];
@@ -156,13 +227,16 @@ export function chunkPageForEmbedding(
       ? [cleanContent]
       : splitAtSentenceBoundaries(cleanContent, maxChars);
 
+    const prefix = getEmbeddingPrefix(pageTitle, section.heading, slug, page.frontmatter);
+
     for (const piece of pieces) {
       if (!piece.trim()) continue;
       chunks.push({
         id: `${slug}#${chunkIndex}`,
         pageSlug: slug,
         sectionHeading: section.heading,
-        content: embeddingPrefix + piece,
+        content: piece,
+        prefix,
         pageTitle,
       });
       chunkIndex++;

package/vendored/lib/query-rewriter.ts

@@ -0,0 +1,91 @@
+/**
+ * Lightweight query rewriter for AI chat retrieval.
+ *
+ * Translates vague/natural-language user queries into doc-search vocabulary
+ * using Claude Haiku. Runs in parallel with the original query in the chat
+ * route, so latency is masked — if the rewrite is slow or fails, the caller
+ * falls back to the original query without penalty.
+ *
+ * Design notes:
+ * - Returns null on ANY failure path (no client, API error, empty response).
+ *   Callers must handle null by using the original query.
+ * - max_tokens is capped at 80 — rewrites are 3-10 words typically.
+ * - Conversation history is included so follow-ups like "what about the other
+ *   one" can be disambiguated against the prior user message.
+ */
+import { getAnthropicClient } from '@/lib/anthropic-client';
+
+const REWRITE_MODEL = 'claude-haiku-4-5-20251001';
+const MAX_REWRITE_CHARS = 200;
+
+export const SYSTEM_PROMPT = `You rewrite a user's chat question into a short documentation search query.
+
+Rules:
+- Output ONLY the rewritten query — no quotes, no explanation, no prefix.
+- Use terminology that would appear in technical documentation.
+- Keep it short (3-10 words is ideal).
+- If the user's question already uses technical vocabulary, output it unchanged.
+- If conversation history is provided, use it to disambiguate references like "the other one" or "that".
+
+Examples:
+Q: how do I make my docs live → deploy documentation site
+Q: change colors → theme customization
+Q: can it do auth → authentication setup
+Q: what about the other one (after discussing analytics) → link analytics
+Q: what is the most recent feature → changelog latest updates new features
+Q: what's new → changelog new features updates
+Q: latest release → changelog release notes updates
+Q: any updates recently → changelog recent updates new features`;
+
+export interface HistoryMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Rewrite a user query into doc-search vocabulary.
+ * Returns null on any failure — caller should fall back to the original query.
+ */
+export async function rewriteQueryForSearch(
+  message: string,
+  history: HistoryMessage[],
+): Promise<string | null> {
+  const anthropic = getAnthropicClient();
+  if (!anthropic) return null;
+
+  // Compose the user prompt: include the last user message from history (if any)
+  // so follow-up references resolve. Ignore assistant replies — they'd contaminate
+  // the rewrite with doc-flavored phrasing that might mask the user's real intent.
+  const priorUserMsg = [...history].reverse().find(
+    h => h.role === 'user' && h.content !== message,
+  );
+
+  const userPrompt = priorUserMsg
+    ? `Previous question: ${priorUserMsg.content}\nCurrent question: ${message}\n\nRewrite the current question:`
+    : `Question: ${message}\n\nRewrite:`;
+
+  try {
+    const response = await anthropic.messages.create({
+      model: REWRITE_MODEL,
+      max_tokens: 80,
+      temperature: 0.1,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: 'user', content: userPrompt }],
+    });
+
+    const textBlock = response.content.find(c => c.type === 'text');
+    if (!textBlock || textBlock.type !== 'text') return null;
+
+    let rewrite = textBlock.text.trim();
+
+    // Strip surrounding quotes if Claude wrapped the output
+    rewrite = rewrite.replace(/^["'`]+|["'`]+$/g, '').trim();
+
+    if (!rewrite) return null;
+
+    // Defensive cap — prevents a runaway response from bloating the search query
+    return rewrite.slice(0, MAX_REWRITE_CHARS);
+  } catch {
+    return null;
+  }
+}

package/vendored/lib/r2-content.ts

@@ -23,8 +23,12 @@ export function evictOldest<K, V>(cache: Map<K, V>, maxSize: number): void {
 export function clearConfigCache(_projectSlug?: string): void {}
 export function getConfigCacheSize(): number { return 0; }
 
+let fetchDocsConfigWarned = false;
 export async function fetchDocsConfig(_projectSlug: string): Promise<DocsConfig | null> {
-  console.warn('[r2-content stub] fetchDocsConfig called in dev mode');
+  if (!fetchDocsConfigWarned) {
+    fetchDocsConfigWarned = true;
+    console.warn('[r2-content stub] fetchDocsConfig called in dev mode (suppressing further warnings)');
+  }
   return null;
 }
 

package/vendored/lib/vector-store.ts

@@ -44,8 +44,8 @@ const HYBRID_QUERY_OPTS = {
  */
 const MIN_SCORE = 0.3;
 
-/** Max chunks per page — ensures diverse results across pages */
-const MAX_CHUNKS_PER_PAGE = 3;
+/** Max chunks per page — raised from 3 to 4 to match broader topK retrieval budget */
+const MAX_CHUNKS_PER_PAGE = 4;
 
 /** Create a namespaced Upstash Vector index for a project. */
 function getNamespace(projectId: string) {
@@ -80,7 +80,9 @@ export async function upsertChunks(
     await ns.upsert(
       batch.map(c => ({
         id: c.id,
-        data: c.content,
+        // Prefix + body goes to Upstash for embedding/BM25; metadata.content
+        // stays prefix-free so consumers display clean body text.
+        data: c.prefix + c.content,
         metadata: {
           pageSlug: c.pageSlug,
           sectionHeading: c.sectionHeading,