chore: import upstream snapshot with attribution

apps/docs/app/api/chat/route.ts

@@ -0,0 +1,344 @@
+import { openai } from '@ai-sdk/openai'
+import { convertToModelMessages, stepCountIs, streamText, tool, type UIMessage } from 'ai'
+import { sql } from 'drizzle-orm'
+import { z } from 'zod'
+import { db, docsEmbeddings } from '@/lib/db'
+import { generateSearchEmbedding } from '@/lib/embeddings'
+
+export const runtime = 'nodejs'
+export const maxDuration = 30
+
+/** Model used for the Ask AI chat. Override with OPENAI_CHAT_MODEL in the environment. */
+const CHAT_MODEL = process.env.OPENAI_CHAT_MODEL || 'gpt-5.4-mini'
+
+/** Max documentation chunks returned per search to ground an answer. */
+const SEARCH_LIMIT = 6
+
+/** Candidates pulled before locale filtering, so a locale still yields SEARCH_LIMIT results. */
+const SEARCH_CANDIDATES = SEARCH_LIMIT * 4
+
+/** Minimum cosine similarity for an English vector match (mirrors the site search route). */
+const SIMILARITY_THRESHOLD = 0.6
+
+/** Locales the docs are published in (mirrors the site search route). */
+const KNOWN_LOCALES = ['en', 'es', 'fr', 'de', 'ja', 'zh']
+const DEFAULT_LOCALE = 'en'
+
+/** Postgres full-text config per locale (mirrors the site search route). */
+const TS_CONFIG: Record<string, string> = {
+  en: 'english',
+  es: 'spanish',
+  fr: 'french',
+  de: 'german',
+  ja: 'simple',
+  zh: 'simple',
+}
+
+/**
+ * Abuse guards. This endpoint proxies a paid LLM, so an unauthenticated public
+ * route is a target for scripted "free inference". These bounds cap the cost of
+ * any single request; an in-memory per-IP rate limit (below) caps volume on the
+ * hot path. A shared-store rate limit, a provider spend cap, and edge bot
+ * protection remain the durable controls (see the PR checklist).
+ *
+ * The size cap counts only user-authored text — NOT the conversation history,
+ * assistant turns, or retrieved doc chunks we add via the searchDocs tool, which
+ * legitimately grow large over a multi-turn chat.
+ */
+const MAX_MESSAGES = 200
+const MAX_USER_INPUT_CHARS = 400_000
+const MAX_OUTPUT_TOKENS = 4000
+const MAX_STEPS = 6
+/** Backstop on the sanitized model payload — bounds total LLM input (e.g. stuffed assistant text). */
+const MAX_TOTAL_CHARS = 1_000_000
+
+/**
+ * Per-IP rate limit. Fixed window, in-memory: this bounds volume from a single
+ * source on a warm instance without external infra. It is best-effort on
+ * serverless (state is per-instance, not shared across regions/cold starts);
+ * a shared store (e.g. Vercel KV) and an edge WAF remain the durable controls,
+ * but this closes the "no volume limit at all" gap on the hot path.
+ */
+const RATE_LIMIT_MAX = 20
+const RATE_LIMIT_WINDOW_MS = 60_000
+const rateLimitHits = new Map<string, { count: number; resetAt: number }>()
+
+/** Resolve the client IP from forwarding headers, falling back to a shared bucket. */
+function getClientIp(req: Request): string {
+  const forwarded = req.headers.get('x-forwarded-for')
+  if (forwarded) return forwarded.split(',')[0].trim()
+  return req.headers.get('x-real-ip') ?? 'unknown'
+}
+
+/** Fixed-window check. Returns retry-after seconds when the caller is over the limit, else null. */
+function rateLimit(ip: string, now: number): number | null {
+  const entry = rateLimitHits.get(ip)
+  if (!entry || now >= entry.resetAt) {
+    rateLimitHits.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
+    return null
+  }
+  if (entry.count >= RATE_LIMIT_MAX) {
+    return Math.ceil((entry.resetAt - now) / 1000)
+  }
+  entry.count += 1
+  return null
+}
+
+/** Drop expired buckets so the Map doesn't grow unbounded on a long-lived instance. */
+function sweepRateLimit(now: number): void {
+  if (rateLimitHits.size < 10_000) return
+  for (const [ip, entry] of rateLimitHits) {
+    if (now >= entry.resetAt) rateLimitHits.delete(ip)
+  }
+}
+
+/** A structurally valid UI message: has a role and a parts array. */
+function isValidMessage(message: unknown): message is UIMessage {
+  return (
+    typeof message === 'object' &&
+    message !== null &&
+    typeof (message as { role?: unknown }).role === 'string' &&
+    Array.isArray((message as { parts?: unknown }).parts)
+  )
+}
+
+/** Total length of user-authored text across the conversation. */
+function userInputChars(messages: UIMessage[]): number {
+  let total = 0
+  for (const message of messages) {
+    if (message.role !== 'user') continue
+    for (const part of message.parts) {
+      if (part.type === 'text' && typeof part.text === 'string') total += part.text.length
+    }
+  }
+  return total
+}
+
+/**
+ * Strip everything the model shouldn't trust from client-supplied history:
+ * drop `system` messages (client-injected instructions) and every non-text part
+ * (e.g. crafted tool results faking searchDocs output). Only user/assistant text
+ * survives, so grounding comes from the server-run searchDocs tool — not the
+ * client's payload.
+ */
+function sanitizeMessages(messages: UIMessage[]): UIMessage[] {
+  return messages
+    .filter((message) => message.role === 'user' || message.role === 'assistant')
+    .map((message) => ({
+      ...message,
+      parts: message.parts.filter((part) => part.type === 'text' && typeof part.text === 'string'),
+    }))
+    .filter((message) => message.parts.length > 0)
+}
+
+/**
+ * Reject obvious cross-origin calls. Same-origin browser requests send an
+ * `Origin` header matching the host; we allow those, plus any host in
+ * DOCS_ALLOWED_ORIGINS (comma-separated). Requests with no Origin (e.g. curl)
+ * are allowed through to the cost caps rather than blocked, since Origin is
+ * trivially spoofable and is a filter, not a security boundary.
+ */
+function isAllowedOrigin(req: Request): boolean {
+  const origin = req.headers.get('origin')
+  if (!origin) return true
+
+  let originHost: string
+  try {
+    originHost = new URL(origin).host.toLowerCase()
+  } catch {
+    return false
+  }
+
+  const forwardedHost = req.headers.get('x-forwarded-host') ?? req.headers.get('host')
+  const requestHost = forwardedHost?.split(',')[0].trim().toLowerCase()
+  if (requestHost && originHost === requestHost) return true
+
+  const allowlist = (process.env.DOCS_ALLOWED_ORIGINS ?? '')
+    .split(',')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean)
+  return allowlist.includes(originHost)
+}
+
+const SYSTEM_PROMPT = `You are the documentation assistant for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.
+
+Answer questions about Sim using the documentation. Always call the searchDocs tool before answering anything specific about Sim's features, configuration, or usage — do not answer from memory. Base your answer only on the returned documentation; if the docs do not cover the question, say so plainly rather than guessing.
+
+Guidelines:
+- Be direct and concrete. Lead with the answer, then the detail.
+- Reference the relevant pages by their titles so the user knows where to read more.
+- When you show configuration or code, keep it minimal and correct.
+- The agent is called "Sim" and the chat surface is "Chat" — never say "Mothership" or "copilot".
+- If a question is unrelated to Sim, briefly say it's outside the docs' scope.`
+
+const SEARCH_COLUMNS = {
+  chunkId: docsEmbeddings.chunkId,
+  title: docsEmbeddings.headerText,
+  url: docsEmbeddings.sourceLink,
+  content: docsEmbeddings.chunkText,
+  sourceDocument: docsEmbeddings.sourceDocument,
+}
+
+/** Reciprocal-rank-fusion constant, matching the site search route. */
+const RRF_K = 60
+
+/**
+ * SQL predicate selecting only the locale's documents, so the row limit applies
+ * to matching rows: non-English docs are prefixed with their locale segment;
+ * English is everything not prefixed with another locale.
+ */
+function localeFilter(locale: string) {
+  const firstSegment = sql`split_part(${docsEmbeddings.sourceDocument}, '/', 1)`
+  if (locale === DEFAULT_LOCALE) {
+    const others = KNOWN_LOCALES.filter((l) => l !== DEFAULT_LOCALE)
+    return sql`${firstSegment} not in (${sql.join(
+      others.map((l) => sql`${l}`),
+      sql`, `
+    )})`
+  }
+  return sql`${firstSegment} = ${locale}`
+}
+
+type SearchRow = {
+  chunkId: string
+  title: string
+  url: string
+  content: string
+  sourceDocument: string
+}
+
+/**
+ * Retrieve candidate chunks for grounding, mirroring the site search route's
+ * hybrid strategy: Postgres full-text keyword search for every locale, plus
+ * vector similarity (thresholded) for English — fused by reciprocal rank so a
+ * page found by either signal can ground the answer.
+ */
+async function searchDocs(query: string, locale: string) {
+  const tsConfig = TS_CONFIG[locale] ?? 'simple'
+
+  // Each retrieval path is best-effort and independent: a failure in one still
+  // lets the other ground the answer (both empty just yields no grounding).
+  let keywordRows: SearchRow[] = []
+  try {
+    keywordRows = await db
+      .select(SEARCH_COLUMNS)
+      .from(docsEmbeddings)
+      .where(
+        sql`${docsEmbeddings.chunkTextTsv} @@ plainto_tsquery(${tsConfig}, ${query}) and ${localeFilter(locale)}`
+      )
+      .orderBy(
+        sql`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query})) DESC`
+      )
+      .limit(SEARCH_CANDIDATES)
+  } catch (error) {
+    console.error('Ask AI keyword search failed:', error)
+  }
+
+  let vectorRows: SearchRow[] = []
+  if (locale === DEFAULT_LOCALE) {
+    // Vector retrieval (embedding call + pgvector query) is best-effort: if it
+    // fails, fall back to the keyword rows already fetched rather than losing all
+    // grounding for the turn.
+    try {
+      const embedding = await generateSearchEmbedding(query)
+      const vectorLiteral = JSON.stringify(embedding)
+      vectorRows = await db
+        .select(SEARCH_COLUMNS)
+        .from(docsEmbeddings)
+        .where(
+          sql`1 - (${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector) >= ${SIMILARITY_THRESHOLD} and ${localeFilter(locale)}`
+        )
+        .orderBy(sql`${docsEmbeddings.embedding} <=> ${vectorLiteral}::vector`)
+        .limit(SEARCH_CANDIDATES)
+    } catch (error) {
+      console.error('Ask AI vector search failed; using keyword results only:', error)
+    }
+  }
+
+  // Reciprocal rank fusion across the two rankings, deduped by chunk.
+  const scores = new Map<string, number>()
+  const rowById = new Map<string, SearchRow>()
+  for (const list of [vectorRows, keywordRows]) {
+    list.forEach((row, index) => {
+      scores.set(row.chunkId, (scores.get(row.chunkId) ?? 0) + 1 / (RRF_K + index + 1))
+      if (!rowById.has(row.chunkId)) rowById.set(row.chunkId, row)
+    })
+  }
+
+  return [...rowById.values()]
+    .sort((a, b) => (scores.get(b.chunkId) ?? 0) - (scores.get(a.chunkId) ?? 0))
+    .slice(0, SEARCH_LIMIT)
+    .map((row) => ({
+      title: row.title,
+      url: row.url,
+      content: row.content,
+    }))
+}
+
+export async function POST(req: Request) {
+  if (!isAllowedOrigin(req)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+
+  const now = Date.now()
+  sweepRateLimit(now)
+  const retryAfter = rateLimit(getClientIp(req), now)
+  if (retryAfter !== null) {
+    return new Response('Too many requests', {
+      status: 429,
+      headers: { 'Retry-After': String(retryAfter) },
+    })
+  }
+
+  let body: { messages: UIMessage[]; locale?: string }
+  try {
+    body = await req.json()
+  } catch {
+    return new Response('Invalid JSON', { status: 400 })
+  }
+  const { messages } = body
+  const locale = KNOWN_LOCALES.includes(body.locale ?? '')
+    ? (body.locale as string)
+    : DEFAULT_LOCALE
+
+  if (!Array.isArray(messages) || messages.length === 0 || messages.length > MAX_MESSAGES) {
+    return new Response('Invalid request', { status: 400 })
+  }
+  if (!messages.every(isValidMessage)) {
+    return new Response('Invalid request', { status: 400 })
+  }
+  if (userInputChars(messages) > MAX_USER_INPUT_CHARS) {
+    return new Response('Request too large', { status: 413 })
+  }
+
+  const modelMessages = sanitizeMessages(messages)
+  if (modelMessages.length === 0) {
+    return new Response('Invalid request', { status: 400 })
+  }
+  // Bound what actually reaches the model. Measured AFTER sanitization, so the
+  // prior searchDocs tool outputs that accumulate in client history (and are
+  // stripped here) don't count — only user/assistant text the model will see.
+  if (JSON.stringify(modelMessages).length > MAX_TOTAL_CHARS) {
+    return new Response('Request too large', { status: 413 })
+  }
+
+  const result = streamText({
+    model: openai(CHAT_MODEL),
+    system: SYSTEM_PROMPT,
+    messages: convertToModelMessages(modelMessages),
+    stopWhen: stepCountIs(MAX_STEPS),
+    maxOutputTokens: MAX_OUTPUT_TOKENS,
+    tools: {
+      searchDocs: tool({
+        description:
+          'Search the Sim documentation for relevant content. Use this before answering any question about Sim.',
+        inputSchema: z.object({
+          query: z.string().describe('A focused natural-language search query.'),
+        }),
+        execute: async ({ query }) => searchDocs(query, locale),
+      }),
+    },
+  })
+
+  return result.toUIMessageStreamResponse()
+}

apps/docs/app/api/og/route.tsx

@@ -0,0 +1,232 @@
+import type { CSSProperties } from 'react'
+import { ImageResponse } from 'next/og'
+import type { NextRequest } from 'next/server'
+
+export const runtime = 'edge'
+
+const TITLE_FONT_SIZE = {
+  large: 110,
+  medium: 96,
+  small: 85,
+} as const
+/** Average glyph width as a fraction of font size, for this weight/family — used to pack words into lines. */
+const LATIN_CHAR_WIDTH_EM = 0.42
+/** CJK glyphs (docs ships `ja`/`zh` locales) render near-square, roughly 2.4x a Latin glyph at this weight. */
+const CJK_CHAR_WIDTH_EM = 1
+const CJK_RANGE = /[\u3000-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff00-\uffef]/
+const TITLE_BOX_WIDTH = 1020
+const FONT_CACHE_REVALIDATE_SECONDS = 60 * 60 * 24 * 30
+/** Exact hex from a vector trace of the reference cover template, not an estimate off compressed JPEG pixels. */
+const INK_COLOR = '#515151'
+const OG_CONTAINER_STYLE = {
+  height: '100%',
+  width: '100%',
+  display: 'flex',
+  flexDirection: 'column',
+  justifyContent: 'space-between',
+  padding: '26px',
+  background: '#c1c1c1',
+  fontFamily: 'Soehne',
+} satisfies CSSProperties
+const OG_HEADER_STYLE = {
+  display: 'flex',
+  justifyContent: 'space-between',
+  alignItems: 'flex-start',
+  width: '100%',
+} satisfies CSSProperties
+const OG_TITLE_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  fontWeight: 500,
+  color: INK_COLOR,
+  lineHeight: 1.1,
+  width: `${TITLE_BOX_WIDTH}px`,
+  /** Compensates for Satori adding extra invisible leading below the last line instead of splitting it evenly. */
+  transform: 'translateY(14px)',
+} satisfies CSSProperties
+
+function getTitleFontSize(title: string): number {
+  if (title.length > 45) return TITLE_FONT_SIZE.small
+  if (title.length > 30) return TITLE_FONT_SIZE.medium
+  return TITLE_FONT_SIZE.large
+}
+
+function getTitleStyle(title: string): CSSProperties {
+  return {
+    ...OG_TITLE_STYLE,
+    fontSize: getTitleFontSize(title),
+  }
+}
+
+/** Sums per-character em-widths rather than counting characters, so wide CJK glyphs (docs ships `ja`/`zh`) don't under-wrap. */
+function estimateWidthEm(text: string): number {
+  let width = 0
+  for (const char of text) {
+    width += CJK_RANGE.test(char) ? CJK_CHAR_WIDTH_EM : LATIN_CHAR_WIDTH_EM
+  }
+  return width
+}
+
+/**
+ * Splits a single word wider than `maxWidthEm` into character-level chunks
+ * that each fit. CJK titles (docs ships `ja`/`zh` locales) are often
+ * space-free, so a whole run can arrive as one "word" from `wrapTitleLines`'
+ * space-based split. Breaking mid-word is correct for CJK, where each glyph
+ * is independently readable; Latin words never reach this path since they
+ * stay under `maxWidthEm` in practice.
+ */
+function splitOversizedWord(word: string, maxWidthEm: number): string[] {
+  const chunks: string[] = []
+  let chunk = ''
+
+  for (const char of word) {
+    const candidate = chunk + char
+    if (estimateWidthEm(candidate) > maxWidthEm && chunk) {
+      chunks.push(chunk)
+      chunk = char
+    } else {
+      chunk = candidate
+    }
+  }
+  if (chunk) chunks.push(chunk)
+
+  return chunks
+}
+
+/**
+ * Greedily packs words into lines that fit `TITLE_BOX_WIDTH` at `fontSize`,
+ * then joins each line with U+00A0 instead of a plain space. Satori
+ * (`next/og`'s renderer) has a text-measurement bug where the first plain
+ * space (U+0020) in a text node renders at roughly double width — a
+ * non-breaking space measures correctly and reads identically at this size,
+ * so it sidesteps the bug instead of fighting Satori's own line-wrapping
+ * (which is also disabled here — lines are pre-split, not auto-wrapped).
+ */
+function wrapTitleLines(title: string, fontSize: number): string[] {
+  const maxWidthEm = TITLE_BOX_WIDTH / fontSize
+  const words = title.split(' ')
+  const lines: string[] = []
+  let current = ''
+
+  for (const word of words) {
+    if (estimateWidthEm(word) > maxWidthEm) {
+      if (current) {
+        lines.push(current)
+        current = ''
+      }
+      const chunks = splitOversizedWord(word, maxWidthEm)
+      lines.push(...chunks.slice(0, -1))
+      current = chunks[chunks.length - 1] ?? ''
+      continue
+    }
+
+    const candidate = current ? `${current} ${word}` : word
+    if (estimateWidthEm(candidate) > maxWidthEm && current) {
+      lines.push(current)
+      current = word
+    } else {
+      current = candidate
+    }
+  }
+  if (current) lines.push(current)
+
+  return lines.map((line) => line.replace(/ /g, ' '))
+}
+
+/**
+ * Loads Söhne Kräftig (weight 500), the typeface used on the reference cover
+ * template this OG image matches. Converted to a plain TTF from the
+ * last-shipped `soehne-kraftig.woff2` since Satori (`next/og`'s renderer)
+ * can't parse WOFF2 or variable fonts. Fetched over HTTP since the edge
+ * runtime has no filesystem access — served from `/static/fonts/` (not
+ * `/fonts/`) so it isn't intercepted by the site's i18n proxy (`proxy.ts`),
+ * whose matcher excludes `static` but not `fonts`.
+ */
+async function loadTitleFont(baseUrl: string): Promise<ArrayBuffer> {
+  const response = await fetch(new URL('/static/fonts/Soehne-Kraftig.ttf', baseUrl), {
+    next: { revalidate: FONT_CACHE_REVALIDATE_SECONDS },
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to load font data: ${response.status} ${response.statusText}`)
+  }
+
+  return await response.arrayBuffer()
+}
+
+/** "sim" wordmark, no icon — same brandbook workmark geometry as the docs navbar/landing OG cards. */
+function SimWordmark() {
+  return (
+    <svg width='118' height='57' viewBox='0 0 800 386' fill='none'>
+      <path
+        d='M0 293.75h53.4128c0 14.748 5.3413 26.506 16.0239 35.275 10.6826 8.37 25.1238 12.555 43.3233 12.555 19.783 0 35.016-3.786 45.698-11.36 10.683-7.971 16.024-18.534 16.024-31.687 0-9.566-2.967-17.538-8.902-23.915-5.539-6.378-15.826-11.559-30.861-15.545l-51.0389-11.958c-25.7173-6.377-44.9063-16.142-57.5672-29.296-12.2651-13.153-18.39771-30.491-18.39771-52.015 0-17.936 4.55001-33.481 13.64991-46.635 9.4957-13.153 22.3543-23.3169 38.576-30.4914 16.6173-7.1745 35.6086-10.7619 56.9739-10.7619 21.365 0 39.763 3.7866 55.193 11.3598 15.826 7.5731 28.091 18.1355 36.796 31.6875 9.1 13.552 13.847 29.695 14.243 48.428h-53.413c-.395-15.146-5.341-26.904-14.837-35.275-9.495-8.37-22.75-12.555-39.763-12.555-17.4083 0-30.8604 3.786-40.356 11.36-9.4956 7.573-14.2434 17.936-14.2434 31.089 0 19.531 14.2434 32.884 42.7304 40.058l51.039 12.556c24.53 5.58 42.928 14.747 55.193 27.502 12.265 12.356 18.398 29.296 18.398 50.82 0 18.335-4.946 34.477-14.837 48.428-9.891 13.552-23.541 24.114-40.95 31.687-17.013 7.175-37.191 10.762-60.534 10.762-34.0265 0-61.1285-8.37-81.3067-25.111-20.1782-16.74-30.2673-39.061-30.2673-66.962z'
+        fill={INK_COLOR}
+      />
+      <path
+        d='m267.175 385.826v-292.3631c22.244 8.1331 32.053 8.1331 55.787 0v292.3631zm27.3-311.6891c-9.891 0-18.596-3.5872-26.113-10.7618-7.122-7.5731-10.683-16.342-10.683-26.3067 0-10.3632 3.561-19.132 10.683-26.3066 7.517-7.17453 16.222-10.7618 26.113-10.7618 10.287 0 18.991 3.58727 26.113 10.7618 7.122 7.1746 10.682 15.9434 10.682 26.3066 0 9.9647-3.56 18.7336-10.682 26.3067-7.122 7.1746-15.826 10.7618-26.113 10.7618z'
+        fill={INK_COLOR}
+      />
+      <path
+        d='m421.362 385.823h-55.786v-292.3624h49.852v49.3294c5.934-16.342 17.408-30.197 33.234-40.959 16.222-11.1605 35.807-16.7407 58.754-16.7407 25.718 0 47.083 6.9752 64.096 20.9257 17.013 13.951 28.091 32.485 33.234 55.603h-10.089c3.957-23.118 14.837-41.652 32.642-55.603 17.804-13.9505 39.762-20.9257 65.875-20.9257 33.235 0 59.348 9.7653 78.339 29.2957 18.991 19.531 28.487 46.236 28.487 80.116v191.321h-54.6v-177.57c0-23.118-5.934-40.855-17.804-53.211-11.474-12.755-27.102-19.132-46.885-19.132-13.847 0-26.113 3.189-36.795 9.566-10.287 5.979-18.398 14.748-24.333 26.307-5.934 11.559-8.902 25.111-8.902 40.655v173.385h-55.193v-178.168c0-23.118-5.737-40.655-17.211-52.613-11.474-12.356-27.102-18.534-46.885-18.534-13.847 0-26.112 3.189-36.795 9.566-10.287 5.979-18.398 14.748-24.333 26.307-5.934 11.16-8.902 24.513-8.902 40.057z'
+        fill={INK_COLOR}
+      />
+    </svg>
+  )
+}
+
+/** Diagonal "open" arrow, top-right — square caps and a miter join to match the reference's sharp corners. */
+function CornerArrow() {
+  return (
+    <svg width='58' height='58' viewBox='0 0 24 24' fill='none'>
+      <path
+        d='M2 22 22 2M22 2H12M22 2V12'
+        stroke={INK_COLOR}
+        strokeWidth={3.6}
+        strokeLinecap='square'
+        strokeLinejoin='miter'
+      />
+    </svg>
+  )
+}
+
+/**
+ * Generates dynamic Open Graph images for documentation pages. Matches the
+ * site's library/blog cover template: light gray background, "sim" wordmark
+ * top-left, an open/diagonal arrow top-right, and the page title large and
+ * bold at the bottom-left.
+ */
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url)
+  const title = searchParams.get('title') || 'Documentation'
+
+  const fontData = await loadTitleFont(request.url)
+  const fontSize = getTitleFontSize(title)
+  const titleLines = wrapTitleLines(title, fontSize)
+
+  return new ImageResponse(
+    <div style={OG_CONTAINER_STYLE}>
+      <div style={OG_HEADER_STYLE}>
+        <SimWordmark />
+        <CornerArrow />
+      </div>
+
+      <div style={getTitleStyle(title)}>
+        {titleLines.map((line, index) => (
+          <span key={index}>{line}</span>
+        ))}
+      </div>
+    </div>,
+    {
+      width: 1200,
+      height: 675,
+      fonts: [
+        {
+          name: 'Soehne',
+          data: fontData,
+          style: 'normal',
+          weight: 500,
+        },
+      ],
+    }
+  )
+}

apps/docs/app/api/search/route.ts

@@ -0,0 +1,239 @@
+import { sql } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { db, docsEmbeddings } from '@/lib/db'
+import { generateSearchEmbedding } from '@/lib/embeddings'
+
+export const runtime = 'nodejs'
+export const revalidate = 0
+
+const DEFAULT_SEARCH_LIMIT = 10
+const MAX_SEARCH_LIMIT = 20
+
+function getSearchLimit(value: unknown): number {
+  const limit = Number.parseInt(String(value ?? DEFAULT_SEARCH_LIMIT), 10)
+
+  if (!Number.isFinite(limit) || limit <= 0) {
+    return DEFAULT_SEARCH_LIMIT
+  }
+
+  return Math.min(limit, MAX_SEARCH_LIMIT)
+}
+
+function getSearchParams(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams
+  return {
+    query: searchParams.get('query') || searchParams.get('q') || '',
+    locale: searchParams.get('locale') || 'en',
+    limit: getSearchLimit(searchParams.get('limit')),
+  }
+}
+
+/**
+ * Hybrid search API endpoint
+ * - English: Vector embeddings + keyword search
+ * - Other languages: Keyword search only
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const { query, locale, limit } = getSearchParams(request)
+
+    if (!query || query.trim().length === 0) {
+      return NextResponse.json([])
+    }
+
+    const candidateLimit = limit * 3
+    const similarityThreshold = 0.6
+
+    const localeMap: Record<string, string> = {
+      en: 'english',
+      es: 'spanish',
+      fr: 'french',
+      de: 'german',
+      ja: 'simple', // PostgreSQL doesn't have Japanese support, use simple
+      zh: 'simple', // PostgreSQL doesn't have Chinese support, use simple
+    }
+    const tsConfig = localeMap[locale] || 'simple'
+
+    const useVectorSearch = locale === 'en'
+    let vectorResults: Array<{
+      chunkId: string
+      chunkText: string
+      sourceDocument: string
+      sourceLink: string
+      headerText: string
+      headerLevel: number
+      similarity: number
+      searchType: string
+    }> = []
+
+    if (useVectorSearch) {
+      const queryEmbedding = await generateSearchEmbedding(query)
+      vectorResults = await db
+        .select({
+          chunkId: docsEmbeddings.chunkId,
+          chunkText: docsEmbeddings.chunkText,
+          sourceDocument: docsEmbeddings.sourceDocument,
+          sourceLink: docsEmbeddings.sourceLink,
+          headerText: docsEmbeddings.headerText,
+          headerLevel: docsEmbeddings.headerLevel,
+          similarity: sql<number>`1 - (${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector)`,
+          searchType: sql<string>`'vector'`,
+        })
+        .from(docsEmbeddings)
+        .where(
+          sql`1 - (${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector) >= ${similarityThreshold}`
+        )
+        .orderBy(sql`${docsEmbeddings.embedding} <=> ${JSON.stringify(queryEmbedding)}::vector`)
+        .limit(candidateLimit)
+    }
+
+    const keywordResults = await db
+      .select({
+        chunkId: docsEmbeddings.chunkId,
+        chunkText: docsEmbeddings.chunkText,
+        sourceDocument: docsEmbeddings.sourceDocument,
+        sourceLink: docsEmbeddings.sourceLink,
+        headerText: docsEmbeddings.headerText,
+        headerLevel: docsEmbeddings.headerLevel,
+        similarity: sql<number>`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query}))`,
+        searchType: sql<string>`'keyword'`,
+      })
+      .from(docsEmbeddings)
+      .where(sql`${docsEmbeddings.chunkTextTsv} @@ plainto_tsquery(${tsConfig}, ${query})`)
+      .orderBy(
+        sql`ts_rank(${docsEmbeddings.chunkTextTsv}, plainto_tsquery(${tsConfig}, ${query})) DESC`
+      )
+      .limit(candidateLimit)
+
+    const knownLocales = ['en', 'es', 'fr', 'de', 'ja', 'zh']
+
+    const vectorRankMap = new Map<string, number>()
+    vectorResults.forEach((r, idx) => vectorRankMap.set(r.chunkId, idx + 1))
+
+    const keywordRankMap = new Map<string, number>()
+    keywordResults.forEach((r, idx) => keywordRankMap.set(r.chunkId, idx + 1))
+
+    const resultByChunkId = new Map<string, (typeof vectorResults)[number]>()
+    keywordResults.forEach((result) => resultByChunkId.set(result.chunkId, result))
+    vectorResults.forEach((result) => resultByChunkId.set(result.chunkId, result))
+
+    const allChunkIds = new Set([
+      ...vectorResults.map((r) => r.chunkId),
+      ...keywordResults.map((r) => r.chunkId),
+    ])
+
+    const k = 60
+    type ResultWithRRF = (typeof vectorResults)[0] & { rrfScore: number }
+    const scoredResults: ResultWithRRF[] = []
+
+    for (const chunkId of allChunkIds) {
+      const vectorRank = vectorRankMap.get(chunkId) ?? Number.POSITIVE_INFINITY
+      const keywordRank = keywordRankMap.get(chunkId) ?? Number.POSITIVE_INFINITY
+
+      const rrfScore = 1 / (k + vectorRank) + 1 / (k + keywordRank)
+
+      const result = resultByChunkId.get(chunkId)
+
+      if (result) {
+        scoredResults.push({ ...result, rrfScore })
+      }
+    }
+
+    scoredResults.sort((a, b) => b.rrfScore - a.rrfScore)
+
+    const localeFilteredResults = scoredResults.filter((result) => {
+      const firstPart = result.sourceDocument.split('/')[0]
+      if (knownLocales.includes(firstPart)) {
+        return firstPart === locale
+      }
+      return locale === 'en'
+    })
+
+    const queryLower = query.toLowerCase()
+    const getTitleBoost = (result: ResultWithRRF): number => {
+      const fileName = result.sourceDocument
+        .replace('.mdx', '')
+        .split('/')
+        .pop()
+        ?.toLowerCase()
+        ?.replace(/_/g, ' ')
+
+      if (fileName === queryLower) return 0.01
+      if (fileName?.includes(queryLower)) return 0.005
+      return 0
+    }
+
+    localeFilteredResults.sort((a, b) => {
+      return b.rrfScore + getTitleBoost(b) - (a.rrfScore + getTitleBoost(a))
+    })
+
+    const pageMap = new Map<string, ResultWithRRF>()
+
+    for (const result of localeFilteredResults) {
+      const pageKey = result.sourceDocument
+      const existing = pageMap.get(pageKey)
+
+      if (!existing || result.rrfScore > existing.rrfScore) {
+        pageMap.set(pageKey, result)
+      }
+    }
+
+    const deduplicatedResults = Array.from(pageMap.values())
+      .sort((a, b) => b.rrfScore + getTitleBoost(b) - (a.rrfScore + getTitleBoost(a)))
+      .slice(0, limit)
+
+    const searchResults = deduplicatedResults.map((result) => {
+      const title = result.headerText || result.sourceDocument.replace('.mdx', '')
+
+      const pathParts = result.sourceDocument
+        .replace('.mdx', '')
+        .split('/')
+        .reduce<string[]>((parts, part) => {
+          if (part === 'index' || knownLocales.includes(part)) {
+            return parts
+          }
+
+          parts.push(
+            part
+              .replace(/_/g, ' ')
+              .split(' ')
+              .map((word) => {
+                const acronyms = [
+                  'api',
+                  'mcp',
+                  'sdk',
+                  'url',
+                  'http',
+                  'json',
+                  'xml',
+                  'html',
+                  'css',
+                  'ai',
+                ]
+                if (acronyms.includes(word.toLowerCase())) {
+                  return word.toUpperCase()
+                }
+                return word.charAt(0).toUpperCase() + word.slice(1)
+              })
+              .join(' ')
+          )
+
+          return parts
+        }, [])
+
+      return {
+        id: result.chunkId,
+        type: 'page' as const,
+        url: result.sourceLink,
+        content: title,
+        breadcrumbs: pathParts,
+      }
+    })
+
+    return NextResponse.json(searchResults)
+  } catch (error) {
+    console.error('Semantic search error:', error)
+
+    return NextResponse.json([])
+  }
+}