chore: import upstream snapshot with attribution

apps/docs/app/[lang]/[[...slug]]/page.tsx

@@ -0,0 +1,355 @@
+import type React from 'react'
+import type { Root } from 'fumadocs-core/page-tree'
+import { findNeighbour } from 'fumadocs-core/page-tree'
+import type { ApiPageProps } from 'fumadocs-openapi/ui'
+import { createAPIPage } from 'fumadocs-openapi/ui'
+import { Pre } from 'fumadocs-ui/components/codeblock'
+import defaultMdxComponents from 'fumadocs-ui/mdx'
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/page'
+import { notFound } from 'next/navigation'
+import { PageFooter } from '@/components/docs-layout/page-footer'
+import { PageNavigationArrows } from '@/components/docs-layout/page-navigation-arrows'
+import { LLMCopyButton } from '@/components/page-actions'
+import { PageTypeBadge } from '@/components/page-type-badge'
+import { StructuredData } from '@/components/structured-data'
+import { CodeBlock } from '@/components/ui/code-block'
+import { Heading } from '@/components/ui/heading'
+import { ResponseSection } from '@/components/ui/response-section'
+import { i18n } from '@/lib/i18n'
+import { getApiSpecContent, openapi } from '@/lib/openapi'
+import { type PageData, source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+const SUPPORTED_LANGUAGES: Set<string> = new Set(i18n.languages)
+const BASE_URL = DOCS_BASE_URL
+
+const OG_LOCALE_MAP: Record<string, string> = {
+  en: 'en_US',
+  es: 'es_ES',
+  fr: 'fr_FR',
+  de: 'de_DE',
+  ja: 'ja_JP',
+  zh: 'zh_CN',
+}
+
+function resolveLangAndSlug(params: { slug?: string[]; lang: string }) {
+  const isValidLang = SUPPORTED_LANGUAGES.has(params.lang)
+  const lang = isValidLang ? params.lang : 'en'
+  const slug = isValidLang ? params.slug : [params.lang, ...(params.slug ?? [])]
+  return { lang, slug }
+}
+
+const APIPage = createAPIPage(openapi, {
+  playground: { enabled: false },
+  content: {
+    renderOperationLayout: async (slots) => {
+      return (
+        <div className='flex @4xl:flex-row flex-col @4xl:items-start gap-x-6 gap-y-4'>
+          <div className='min-w-0 flex-1'>
+            {slots.header}
+            {slots.apiPlayground}
+            {slots.authSchemes && <div className='api-section-divider'>{slots.authSchemes}</div>}
+            {slots.parameters}
+            {slots.body && <div className='api-section-divider'>{slots.body}</div>}
+            <ResponseSection>{slots.responses}</ResponseSection>
+            {slots.callbacks}
+          </div>
+          <div className='@4xl:sticky @4xl:top-[calc(var(--fd-docs-row-1,2rem)+1rem)] @4xl:w-[400px]'>
+            {slots.apiExample}
+          </div>
+        </div>
+      )
+    },
+  },
+})
+
+export default async function Page(props: { params: Promise<{ slug?: string[]; lang: string }> }) {
+  const params = await props.params
+  const { lang, slug } = resolveLangAndSlug(params)
+  const page = source.getPage(slug, lang)
+  if (!page) notFound()
+
+  const data = page.data as unknown as PageData & {
+    _openapi?: { method?: string }
+    getAPIPageProps?: () => ApiPageProps
+  }
+  const isOpenAPI = '_openapi' in data && data._openapi != null
+  const isApiReference = slug?.some((s) => s === 'api-reference') ?? false
+  // Academy lessons are video-first: drop the "On this page" TOC and go full
+  // width so the lesson hero/video gets the room (chapters live in-page instead).
+  const isAcademy = slug?.[0] === 'academy'
+
+  const pageTreeRecord = source.pageTree as Record<string, Root>
+  const pageTree = pageTreeRecord[lang] ?? pageTreeRecord.en ?? Object.values(pageTreeRecord)[0]
+  const rawNeighbours = pageTree ? findNeighbour(pageTree, page.url) : null
+  // Academy and API Reference are self-contained sections; keep prev/next inside
+  // the section instead of spilling into the main documentation tree. Match both
+  // the section's pages (`/<slug>/...`) and its index (`/<slug>`).
+  const sectionSlug = isApiReference ? 'api-reference' : isAcademy ? 'academy' : null
+  const inSection = (url?: string) =>
+    url != null && (url.includes(`/${sectionSlug}/`) || url.endsWith(`/${sectionSlug}`))
+  const neighbours = sectionSlug
+    ? {
+        previous: inSection(rawNeighbours?.previous?.url) ? rawNeighbours?.previous : undefined,
+        next: inSection(rawNeighbours?.next?.url) ? rawNeighbours?.next : undefined,
+      }
+    : rawNeighbours
+
+  const generateBreadcrumbs = () => {
+    const breadcrumbs: Array<{ name: string; url: string }> = [
+      {
+        name: 'Home',
+        url: BASE_URL,
+      },
+    ]
+
+    const urlParts = page.url.split('/').filter(Boolean)
+    let currentPath = ''
+
+    urlParts.forEach((part, index) => {
+      if (index === 0 && SUPPORTED_LANGUAGES.has(part)) {
+        currentPath = `/${part}`
+        return
+      }
+
+      currentPath += `/${part}`
+
+      const name = part
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ')
+
+      if (index === urlParts.length - 1) {
+        breadcrumbs.push({
+          name: data.title,
+          url: `${BASE_URL}${page.url}`,
+        })
+      } else {
+        breadcrumbs.push({
+          name: name,
+          url: `${BASE_URL}${currentPath}`,
+        })
+      }
+    })
+
+    return breadcrumbs
+  }
+
+  const breadcrumbs = generateBreadcrumbs()
+  const footer = <PageFooter previous={neighbours?.previous} next={neighbours?.next} />
+
+  if (isOpenAPI && data.getAPIPageProps) {
+    const apiProps = data.getAPIPageProps()
+    const apiPageContent = getApiSpecContent(
+      data.title,
+      data.description,
+      apiProps.operations ?? []
+    )
+
+    return (
+      <>
+        <StructuredData
+          title={data.title}
+          description={data.description || ''}
+          url={`${BASE_URL}${page.url}`}
+          lang={lang}
+          breadcrumb={breadcrumbs}
+        />
+        <DocsPage
+          toc={data.toc}
+          breadcrumb={{
+            enabled: false,
+          }}
+          tableOfContent={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          tableOfContentPopover={{
+            style: 'clerk',
+            enabled: false,
+          }}
+          footer={{
+            enabled: true,
+            component: footer,
+          }}
+        >
+          <div className='api-page-header relative mt-6 sm:mt-0'>
+            <div className='absolute top-1 right-0 flex items-center gap-2'>
+              <div className='hidden sm:flex'>
+                <LLMCopyButton content={apiPageContent} />
+              </div>
+              <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
+            </div>
+            <DocsTitle className='mb-2'>{data.title}</DocsTitle>
+          </div>
+          <DocsBody>
+            <APIPage {...apiProps} />
+          </DocsBody>
+        </DocsPage>
+      </>
+    )
+  }
+
+  const MDX = data.body
+  const markdownContent = await data.getText('processed')
+
+  return (
+    <>
+      <StructuredData
+        title={data.title}
+        description={data.description || ''}
+        url={`${BASE_URL}${page.url}`}
+        lang={lang}
+        breadcrumb={breadcrumbs}
+      />
+      <DocsPage
+        toc={data.toc}
+        full={data.full || isAcademy}
+        breadcrumb={{
+          enabled: false,
+        }}
+        tableOfContent={{
+          style: 'clerk',
+          enabled: !isAcademy,
+          single: false,
+        }}
+        tableOfContentPopover={{
+          style: 'clerk',
+          enabled: !isAcademy,
+        }}
+        footer={{
+          enabled: true,
+          component: footer,
+        }}
+      >
+        <div className='relative mt-6 sm:mt-0'>
+          <div className='absolute top-1 right-0 flex items-center gap-2'>
+            <div className='hidden sm:flex'>
+              <LLMCopyButton content={markdownContent} />
+            </div>
+            <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
+          </div>
+          {data.pageType && <PageTypeBadge type={data.pageType} className='mb-3' />}
+          <DocsTitle className='mb-2'>{data.title}</DocsTitle>
+        </div>
+        <DocsBody>
+          <MDX
+            components={{
+              ...defaultMdxComponents,
+              pre: (props: React.HTMLAttributes<HTMLPreElement>) => (
+                <CodeBlock {...props}>
+                  <Pre>{props.children}</Pre>
+                </CodeBlock>
+              ),
+              h1: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h1' {...props} />
+              ),
+              h2: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h2' {...props} />
+              ),
+              h3: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h3' {...props} />
+              ),
+              h4: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h4' {...props} />
+              ),
+              h5: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h5' {...props} />
+              ),
+              h6: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+                <Heading as='h6' {...props} />
+              ),
+            }}
+          />
+        </DocsBody>
+      </DocsPage>
+    </>
+  )
+}
+
+export async function generateStaticParams() {
+  return source.generateParams()
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[]; lang: string }>
+}) {
+  const params = await props.params
+  const { lang, slug } = resolveLangAndSlug(params)
+  const page = source.getPage(slug, lang)
+  if (!page) notFound()
+
+  const data = page.data as unknown as PageData
+  const fullUrl = `${BASE_URL}${page.url}`
+
+  const ogImageUrl = `${BASE_URL}/api/og?title=${encodeURIComponent(data.title)}`
+
+  return {
+    title: data.title,
+    description:
+      data.description ||
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
+    keywords: [
+      'AI agents',
+      'AI workspace',
+      'AI agent builder',
+      'build AI agents',
+      'LLM orchestration',
+      'AI automation',
+      'knowledge base',
+      'AI integrations',
+      data.title?.toLowerCase().split(' '),
+    ]
+      .flat()
+      .filter(Boolean),
+    authors: [{ name: 'Sim Team' }],
+    category: 'Developer Tools',
+    openGraph: {
+      title: data.title,
+      description:
+        data.description ||
+        'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
+      url: fullUrl,
+      siteName: 'Sim Documentation',
+      type: 'article',
+      locale: OG_LOCALE_MAP[lang] ?? 'en_US',
+      alternateLocale: i18n.languages.reduce<string[]>((locales, l) => {
+        if (l !== lang) {
+          locales.push(OG_LOCALE_MAP[l] ?? 'en_US')
+        }
+        return locales
+      }, []),
+      images: [
+        {
+          url: ogImageUrl,
+          width: 1200,
+          height: 675,
+          alt: data.title,
+        },
+      ],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: data.title,
+      description:
+        data.description ||
+        'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents.',
+      images: [ogImageUrl],
+      creator: '@simdotai',
+      site: '@simdotai',
+    },
+    canonical: fullUrl,
+    alternates: {
+      canonical: fullUrl,
+      languages: {
+        'x-default': `${BASE_URL}${page.url.replace(`/${lang}`, '')}`,
+        en: `${BASE_URL}${page.url.replace(`/${lang}`, '')}`,
+        es: `${BASE_URL}/es${page.url.replace(`/${lang}`, '')}`,
+        fr: `${BASE_URL}/fr${page.url.replace(`/${lang}`, '')}`,
+        de: `${BASE_URL}/de${page.url.replace(`/${lang}`, '')}`,
+        ja: `${BASE_URL}/ja${page.url.replace(`/${lang}`, '')}`,
+        zh: `${BASE_URL}/zh${page.url.replace(`/${lang}`, '')}`,
+      },
+    },
+  }
+}

apps/docs/app/[lang]/layout.tsx

@@ -0,0 +1,131 @@
+import type { ReactNode } from 'react'
+import { defineI18nUI } from 'fumadocs-ui/i18n'
+import { DocsLayout } from 'fumadocs-ui/layouts/docs'
+import { RootProvider } from 'fumadocs-ui/provider/next'
+import { Geist_Mono, Inter } from 'next/font/google'
+import { AskAI } from '@/components/ai/ask-ai'
+import {
+  SidebarFolder,
+  SidebarItem,
+  SidebarSeparator,
+} from '@/components/docs-layout/sidebar-components'
+import { Footer } from '@/components/footer/footer'
+import { Navbar } from '@/components/navbar/navbar'
+import { SimWordmark } from '@/components/ui/sim-logo'
+import { i18n } from '@/lib/i18n'
+import { serializeJsonLd } from '@/lib/json-ld'
+import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+import { season } from '@/app/fonts/season'
+import '../global.css'
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-geist-sans',
+  display: 'swap',
+})
+
+const geistMono = Geist_Mono({
+  subsets: ['latin'],
+  variable: '--font-geist-mono',
+  display: 'swap',
+})
+
+const { provider } = defineI18nUI(i18n, {
+  translations: {
+    en: {
+      displayName: 'English',
+    },
+    es: {
+      displayName: 'Español',
+    },
+    fr: {
+      displayName: 'Français',
+    },
+    de: {
+      displayName: 'Deutsch',
+    },
+    ja: {
+      displayName: '日本語',
+    },
+    zh: {
+      displayName: '简体中文',
+    },
+  },
+})
+
+type LayoutProps = {
+  children: ReactNode
+  params: Promise<{ lang: string }>
+}
+
+const SUPPORTED_LANGUAGES: Set<string> = new Set(i18n.languages)
+
+export default async function Layout({ children, params }: LayoutProps) {
+  const { lang: rawLang } = await params
+  const lang = SUPPORTED_LANGUAGES.has(rawLang) ? rawLang : 'en'
+
+  const structuredData = {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: 'Sim Documentation',
+    description:
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+    url: DOCS_BASE_URL,
+    publisher: {
+      '@type': 'Organization',
+      name: 'Sim',
+      url: 'https://sim.ai',
+      logo: {
+        '@type': 'ImageObject',
+        url: `${DOCS_BASE_URL}/static/logo.png`,
+      },
+    },
+    inLanguage: lang,
+  }
+
+  return (
+    <html
+      lang={lang}
+      className={`${inter.variable} ${geistMono.variable} ${season.variable}`}
+      suppressHydrationWarning
+    >
+      <head>
+        <script
+          type='application/ld+json'
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(structuredData) }}
+        />
+      </head>
+      <body className='flex min-h-screen flex-col font-sans'>
+        <RootProvider i18n={provider(lang)}>
+          <Navbar />
+          <DocsLayout
+            tree={source.pageTree[lang]}
+            nav={{
+              title: <SimWordmark className='h-[18px]' />,
+            }}
+            sidebar={{
+              tabs: false,
+              defaultOpenLevel: 0,
+              collapsible: false,
+              footer: null,
+              banner: null,
+              components: {
+                Item: SidebarItem,
+                Folder: SidebarFolder,
+                Separator: SidebarSeparator,
+              },
+            }}
+            containerProps={{
+              className: '!pt-0',
+            }}
+          >
+            {children}
+          </DocsLayout>
+          <Footer />
+          <AskAI locale={lang} />
+        </RootProvider>
+      </body>
+    </html>
+  )
+}

apps/docs/app/[lang]/not-found.tsx

@@ -0,0 +1,25 @@
+import { ChipLink } from '@sim/emcn'
+import { DocsPage } from 'fumadocs-ui/page'
+
+export const metadata = {
+  title: 'Page Not Found',
+}
+
+export default function NotFound() {
+  return (
+    <DocsPage>
+      <div className='flex min-h-[70vh] flex-col items-center justify-center gap-4 text-center'>
+        <h1 className='bg-gradient-to-b from-[var(--brand-accent)] to-[var(--brand-accent-hover)] bg-clip-text font-semibold text-8xl text-transparent'>
+          404
+        </h1>
+        <h2 className='font-semibold text-2xl text-[var(--text-primary)]'>Page Not Found</h2>
+        <p className='text-[var(--text-muted)]'>
+          The page you're looking for doesn't exist or has been moved.
+        </p>
+        <ChipLink href='/' variant='primary'>
+          Go home
+        </ChipLink>
+      </div>
+    </DocsPage>
+  )
+}

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([])
+  }
+}

apps/docs/app/fonts/season.ts

@@ -0,0 +1,16 @@
+import localFont from 'next/font/local'
+
+/**
+ * Season Sans variable font — the platform's UI font, mirrored from
+ * `apps/sim/app/_styles/fonts/season/season.ts` so docs chip chrome renders
+ * with the same typeface as the main app. Variable font supports weights
+ * 300-800.
+ */
+export const season = localFont({
+  src: [{ path: './SeasonSansUprightsVF.woff2', weight: '300 800', style: 'normal' }],
+  display: 'swap',
+  preload: true,
+  variable: '--font-season',
+  fallback: ['system-ui', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'Noto Sans'],
+  adjustFontFallback: 'Arial',
+})

apps/docs/app/layout.tsx

@@ -0,0 +1,112 @@
+import type { ReactNode } from 'react'
+import type { Viewport } from 'next'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return children
+}
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#000000',
+}
+
+export const metadata = {
+  metadataBase: new URL(DOCS_BASE_URL),
+  title: {
+    default: 'Sim Documentation — The AI Workspace for Teams',
+    template: '%s | Sim Docs',
+  },
+  description:
+    'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+  applicationName: 'Sim Docs',
+  generator: 'Next.js',
+  referrer: 'origin-when-cross-origin' as const,
+  keywords: [
+    'AI workspace',
+    'AI agent builder',
+    'AI agents',
+    'build AI agents',
+    'open-source AI agents',
+    'LLM orchestration',
+    'AI integrations',
+    'knowledge base',
+    'AI automation',
+    'visual workflow builder',
+    'enterprise AI',
+    'AI agent deployment',
+    'AI tools',
+  ],
+  authors: [{ name: 'Sim Team', url: 'https://sim.ai' }],
+  creator: 'Sim',
+  publisher: 'Sim',
+  category: 'Developer Tools',
+  classification: 'Developer Documentation',
+  manifest: '/favicon/site.webmanifest',
+  icons: {
+    icon: [{ url: '/icon.svg', type: 'image/svg+xml', sizes: 'any' }],
+    apple: '/favicon/apple-touch-icon.png',
+  },
+  appleWebApp: {
+    capable: true,
+    statusBarStyle: 'default',
+    title: 'Sim Docs',
+  },
+  formatDetection: {
+    telephone: false,
+  },
+  other: {
+    'msapplication-TileColor': '#000000',
+  },
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    alternateLocale: ['es_ES', 'fr_FR', 'de_DE', 'ja_JP', 'zh_CN'],
+    url: DOCS_BASE_URL,
+    siteName: 'Sim Documentation',
+    title: 'Sim Documentation — The AI Workspace for Teams',
+    description:
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+    images: [
+      {
+        url: `${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`,
+        width: 1200,
+        height: 675,
+        alt: 'Sim Documentation',
+      },
+    ],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'Sim Documentation — The AI Workspace for Teams',
+    description:
+      'Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM.',
+    creator: '@simdotai',
+    site: '@simdotai',
+    images: [`${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`],
+  },
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      'max-video-preview': -1,
+      'max-image-preview': 'large',
+      'max-snippet': -1,
+    },
+  },
+  alternates: {
+    canonical: DOCS_BASE_URL,
+    languages: {
+      'x-default': DOCS_BASE_URL,
+      en: DOCS_BASE_URL,
+      es: `${DOCS_BASE_URL}/es`,
+      fr: `${DOCS_BASE_URL}/fr`,
+      de: `${DOCS_BASE_URL}/de`,
+      ja: `${DOCS_BASE_URL}/ja`,
+      zh: `${DOCS_BASE_URL}/zh`,
+    },
+  },
+}

apps/docs/app/llms-full.txt/route.ts

@@ -0,0 +1,31 @@
+import { getLLMText } from '@/lib/llms'
+import { source } from '@/lib/source'
+
+export const revalidate = false
+
+export async function GET() {
+  try {
+    const pages = source.getPages().filter((page) => {
+      if (!page || !page.data || !page.url) return false
+
+      const pathParts = page.url.split('/').filter(Boolean)
+      const hasLangPrefix = pathParts[0] && ['es', 'fr', 'de', 'ja', 'zh'].includes(pathParts[0])
+
+      return !hasLangPrefix
+    })
+
+    const scan = pages.map((page) => getLLMText(page))
+    const scanned = await Promise.all(scan)
+
+    const filtered = scanned.filter((text) => text && text.length > 0)
+
+    return new Response(filtered.join('\n\n---\n\n'), {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+      },
+    })
+  } catch (error) {
+    console.error('Error generating LLM full text:', error)
+    return new Response('Error generating full documentation text', { status: 500 })
+  }
+}

apps/docs/app/llms.mdx/[[...slug]]/route.ts

@@ -0,0 +1,35 @@
+import { notFound } from 'next/navigation'
+import { type NextRequest, NextResponse } from 'next/server'
+import { i18n } from '@/lib/i18n'
+import { getLLMText } from '@/lib/llms'
+import { source } from '@/lib/source'
+
+export const revalidate = false
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ slug?: string[] }> }
+) {
+  const { slug } = await params
+
+  let lang: (typeof i18n.languages)[number] = i18n.defaultLanguage
+  let pageSlug = slug
+
+  if (slug && slug.length > 0 && i18n.languages.includes(slug[0] as typeof lang)) {
+    lang = slug[0] as typeof lang
+    pageSlug = slug.slice(1)
+  }
+
+  const page = source.getPage(pageSlug, lang)
+  if (!page) notFound()
+
+  return new NextResponse(await getLLMText(page), {
+    headers: {
+      'Content-Type': 'text/markdown',
+    },
+  })
+}
+
+export function generateStaticParams() {
+  return source.generateParams()
+}

apps/docs/app/llms.txt/route.ts

@@ -0,0 +1,88 @@
+import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+export const revalidate = false
+
+export async function GET() {
+  const baseUrl = DOCS_BASE_URL
+
+  try {
+    const pages = source.getPages().filter((page) => {
+      if (!page || !page.data || !page.url) return false
+
+      const pathParts = page.url.split('/').filter(Boolean)
+      const hasLangPrefix = pathParts[0] && ['es', 'fr', 'de', 'ja', 'zh'].includes(pathParts[0])
+
+      return !hasLangPrefix
+    })
+
+    const sections: Record<string, Array<{ title: string; url: string; description?: string }>> = {}
+
+    pages.forEach((page) => {
+      const pathParts = page.url.split('/').filter(Boolean)
+      const section =
+        pathParts[0] && ['en', 'es', 'fr', 'de', 'ja', 'zh'].includes(pathParts[0])
+          ? pathParts[1] || 'root'
+          : pathParts[0] || 'root'
+
+      if (!sections[section]) {
+        sections[section] = []
+      }
+
+      sections[section].push({
+        title: page.data.title || 'Untitled',
+        url: `${baseUrl}${page.url}`,
+        description: page.data.description,
+      })
+    })
+
+    const manifest = `# Sim Documentation
+
+> The open-source AI workspace where teams build, deploy, and manage AI agents.
+
+Sim is the open-source AI workspace where teams build, deploy, and manage AI agents. Connect 1,000+ integrations and every major LLM to create agents that automate real work — visually, conversationally, or with code. Trusted by over 100,000 builders.
+
+## Documentation Overview
+
+This file provides an overview of our documentation. For full content of all pages, see [llms-full.txt](${baseUrl}/llms-full.txt).
+
+## Main Sections
+
+${Object.entries(sections)
+  .map(([section, items]) => {
+    const sectionTitle = section
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ')
+    return `### ${sectionTitle}\n\n${items.map((item) => `- [${item.title}](${item.url})${item.description ? `\n  ${item.description}` : ''}`).join('\n')}`
+  })
+  .join('\n\n')}
+
+## Additional Resources
+
+- [Full documentation content](${baseUrl}/llms-full.txt)
+- Individual page content: ${baseUrl}/llms.mdx/[page-path]
+- [API documentation](${baseUrl}/api-reference/)
+- [Tool integrations](${baseUrl}/tools/)
+
+## Statistics
+
+- Total pages: ${pages.length} (English only)
+- Other languages available at: ${baseUrl}/[lang]/ (es, fr, de, ja, zh)
+
+---
+
+Generated: ${new Date().toISOString()}
+Format: llms.txt v0.1.0
+See: https://llmstxt.org for specification`
+
+    return new Response(manifest, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+      },
+    })
+  } catch (error) {
+    console.error('Error generating LLM manifest:', error)
+    return new Response('Error generating documentation manifest', { status: 500 })
+  }
+}

apps/docs/app/robots.txt/route.ts

@@ -0,0 +1,35 @@
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+export const revalidate = false
+
+export async function GET() {
+  const baseUrl = DOCS_BASE_URL
+
+  const robotsTxt = `# Robots.txt for Sim Documentation
+
+User-agent: *
+Disallow: /.next/
+Disallow: /api/internal/
+Disallow: /_next/static/
+Disallow: /admin/
+Allow: /
+Allow: /llms.txt
+Allow: /llms-full.txt
+Allow: /llms.mdx/
+
+# Sitemaps
+Sitemap: ${baseUrl}/sitemap.xml
+
+# Additional resources for AI indexing
+# See https://github.com/AnswerDotAI/llms-txt for more info
+# LLM-friendly content:
+#   Manifest: ${baseUrl}/llms.txt
+#   Full content: ${baseUrl}/llms-full.txt
+#   Individual pages: ${baseUrl}/llms.mdx/[page-path]`
+
+  return new Response(robotsTxt, {
+    headers: {
+      'Content-Type': 'text/plain',
+    },
+  })
+}

apps/docs/app/sitemap.ts

@@ -0,0 +1,42 @@
+import type { MetadataRoute } from 'next'
+import { i18n } from '@/lib/i18n'
+import { source } from '@/lib/source'
+import { DOCS_BASE_URL } from '@/lib/urls'
+
+export const revalidate = 3600
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = DOCS_BASE_URL
+  const languages = source.getLanguages()
+
+  const pagesBySlug = new Map<string, Map<string, string>>()
+  for (const { language, pages } of languages) {
+    for (const page of pages) {
+      const key = page.slugs.join('/')
+      if (!pagesBySlug.has(key)) {
+        pagesBySlug.set(key, new Map())
+      }
+      pagesBySlug.get(key)!.set(language, `${baseUrl}${page.url}`)
+    }
+  }
+
+  const entries: MetadataRoute.Sitemap = []
+  for (const [, localeMap] of pagesBySlug) {
+    const defaultUrl = localeMap.get(i18n.defaultLanguage)
+    if (!defaultUrl) continue
+
+    const langAlternates: Record<string, string> = {}
+    for (const [lang, url] of localeMap) {
+      langAlternates[lang] = url
+    }
+
+    langAlternates['x-default'] = defaultUrl
+
+    entries.push({
+      url: defaultUrl,
+      alternates: { languages: langAlternates },
+    })
+  }
+
+  return entries
+}