blume 1.5.1 → 1.5.2

package/docs/configuration/search.mdx

@@ -67,9 +67,9 @@ search: {
 }
 ```
 
-#### Languages written without spaces
+#### Non-Latin scripts
 
-Orama's standard tokenizer splits on word boundaries that only exist in space-separated scripts, so Japanese, Chinese, Korean, and Thai text would otherwise produce no matches at all. Blume handles this for you: when [`i18n.defaultLocale`](/docs/content/i18n) is one of those languages, the index switches to a word-segmenting tokenizer (built on the browser- and Node-native `Intl.Segmenter`). Declaring your site's language is all it takes:
+Orama's standard tokenizer keeps only basic Latin letters, digits and a handful of accented vowels, so text in any other script — Japanese, Chinese, Korean and Thai, but equally Russian, Greek, Hebrew and Hindi — would otherwise produce no matches at all. Blume handles this for you: when [`i18n.defaultLocale`](/docs/content/i18n) resolves to a non-Latin script, the index switches to a word-segmenting tokenizer (built on the browser- and Node-native `Intl.Segmenter`). Declaring your site's language is all it takes:
 
 ```ts blume.config.ts lineNumbers
 i18n: {
@@ -78,7 +78,7 @@ i18n: {
 }
 ```
 
-The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding. On a mixed-language site the whole index shares the default locale's tokenizer — that's safe, because Latin words survive segmentation intact, so pages in English (or any spaced language) stay searchable alongside the default language.
+The same tokenizer serves the search dialog, the MCP server's `search_docs` tool, and Ask AI grounding. The script is what decides, not the language name — `az-Cyrl` is segmented while `sr-Latn` is not — and it is the default locale that decides for the whole index: on a mixed-language site every page shares the default locale's tokenizer. With a non-Latin default that's safe, because Latin words survive segmentation intact, so pages in English stay searchable alongside the default language. The reverse doesn't hold: non-Latin translations on a Latin-default site aren't searchable. Latin-script languages that lean heavily on diacritics (Vietnamese, or Serbian in Latin script) also fare worse on the standard tokenizer, which folds only a few accented vowels and splits words on the rest.
 
 Japanese and Chinese go one step further. Segmenting alone indexes a compound term as its parts — 資金決済法 as 資金, 決済 and 法 — which lets a page mentioning each part somewhere outrank the page the term is actually about. Han, Hiragana and Katakana are therefore indexed as overlapping character pairs, and queries on those indexes prefer pages carrying a term's pairs together, loosening to any-pair matching when no page carries them all, so typing a whole sentence still returns its closest pages. Korean and Thai keep their segmented words.
 
@@ -86,7 +86,7 @@ Japanese and Chinese go one step further. Segmenting alone indexes a compound te
 
 A second keyless, client-side option. It reuses the same `/blume-search.json` index Orama ships and builds a [FlexSearch](https://github.com/nextapps-de/flexsearch) document index in the browser. Works in `blume dev` and `blume build`.
 
-FlexSearch has no equivalent segmentation hook, so for sites in Japanese, Chinese, Korean, or Thai prefer Orama (the default) or [Pagefind](#pagefind), whose `pagefind_extended` binary segments those languages natively.
+FlexSearch has no equivalent segmentation hook, so for sites in a non-Latin script prefer Orama (the default) or [Pagefind](#pagefind), whose `pagefind_extended` binary indexes a broad set of languages and segments Chinese, Japanese and Korean natively.
 
 ```ts blume.config.ts lineNumbers
 search: {

package/docs/reference/cli.mdx

@@ -123,7 +123,7 @@ Without a project `tsconfig.json`, only the generated runtime is checked.
 
 - **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors.
 - **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on the target page — misses are warnings.
-- **Asset links** (`/logo.png`) are checked against the `public/` directory.
+- **Asset links** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`) against the page's own folder. A plain link to a relative path still resolves as a site route — only image embeds go through the image pipeline.
 - **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.
 
 ## Auditing the built site

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/skills/blume-migrate/SKILL.md

@@ -70,7 +70,7 @@ The single biggest shift for most sources — especially Mintlify — is that **
 - **`navigation`:** `tabs`, `selectors`, `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo`. **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see "Config-declared nesting" above).
 - **`search`** (Orama default, Pagefind opt-in), **`ai`** (llms.txt, Ask AI, the MCP server), **`openapi`**, **`redirects`**, **`seo`**, **`markdown`**, **`analytics`**, **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`**.
 - **Don't set `deployment.site`.** Blume auto-fills it: the dev server's `localhost` URL in dev, and the deployment URL (`VERCEL_PROJECT_PRODUCTION_URL`/`VERCEL_URL`) on Vercel. Hardcoding it in `blume.config.ts` overrides that auto-detection and pins the wrong absolute URL (canonical links, sitemap, OG, llms.txt) everywhere but the one host you typed — so leave it unset even when a source config had a `url`/`site` field. (Sitemap still generates in production because the deploy URL is present there.)
-- **Favicon is a filename convention, not config.** Drop `icon`/`favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` **collapses to one** — pick a single file and report the loss.
+- **Favicon is a filename convention, not config.** Drop `icon`/`favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` maps to a filename pair: copy the light file to a conventional name (e.g. `public/icon.png`) and the dark file to its `-dark` sibling — same directory and extension, `-dark` before the extension (`public/icon-dark.png`). If the two files have different formats, convert one so the extensions match; only an exact sibling of the resolved icon is picked up.
 
 The schema is exported from `blume/schema`; the full field reference is in the `docs/configuration/` directory of the installed `blume` package (see "Full documentation" below for how to locate it).
 

package/skills/blume-migrate/references/mintlify.md

@@ -19,7 +19,7 @@ Resolve `$ref` includes first (Mintlify splits config across files). Map only wh
 | `name` / `title` | `title` |  |
 | `description` | `description` |  |
 | `logo` (string or `{ light, dark, href }`) | `logo` (string, or `{ image: { light, dark, alt }, text, href }`) | Mintlify's `light`/`dark` nest under Blume's `image`; ensure files land in `public/`. **If the SVG is local and monochrome** (a solid black or white mark), rewrite its `fill`/`stroke` to `currentColor` and collapse `{ light, dark }` to the string shorthand `logo: "/logo.svg"` — one file that inherits the theme text color and flips with light/dark automatically. If the logo is a **wordmark** (brand name baked in), set `text: ""` so it doesn't render twice beside `title` |
-| `favicon` (string **or `{ light, dark }`**) | **drop the field** — copy **one** file into `public/` under the conventional name (`favicon.svg`/`icon.png`) | Blume auto-detects by filename; there is **no** favicon config field, and **no** light/dark favicon — a `{ light, dark }` source collapses to one; report the loss |
+| `favicon` (string **or `{ light, dark }`**) | **drop the field** — copy the file(s) into `public/` under conventional names (`favicon.svg`/`icon.png`) | Blume auto-detects by filename; there is **no** favicon config field. A `{ light, dark }` source maps to a filename pair: light file → `public/icon.png`, dark file → its `-dark` sibling `public/icon-dark.png` (same directory and extension — convert if the formats differ) |
 | `colors.primary` + `colors.light` | `theme.accent` (`{ light, dark }`) | accent is now **per-mode**: `accent: { light: <colors.primary>, dark: <colors.light> }`. If Mintlify sets only `primary`, collapse to the string shorthand `accent: "<colors.primary>"` (applies to both modes) |
 | `colors.dark` | `theme.action` |  |
 | `appearance.default` | `theme.mode` (`light`/`dark`/`system`) |  |

package/src/ai/ask-context.ts

@@ -22,8 +22,8 @@ export interface AskPage {
 export interface AskData {
   /**
    * The site's `i18n.defaultLocale`, when i18n is configured. Selects a
-   * word-segmenting Orama tokenizer for languages written without spaces, so
-   * retrieval can match CJK/Thai content.
+   * word-segmenting Orama tokenizer for every non-Latin script, so retrieval
+   * can match CJK, Cyrillic, Greek, Hebrew, or Devanagari content.
    */
   defaultLocale?: string;
   documents: OramaDoc[];
@@ -36,6 +36,34 @@ const MAX_RESULTS = 6;
 const EXCERPT_CHARS = 2000;
 /** Overall cap on injected documentation characters. */
 const CONTEXT_BUDGET = 10_000;
+/**
+ * Smallest excerpt worth injecting. A long page pushed under a tiny residual
+ * budget would get a full `## Title (/route)` heading over a fragment of a few
+ * dozen characters — a section the model is invited to cite but that grounds
+ * nothing. Short pages that fit whole are still injected below this floor.
+ */
+const MIN_EXCERPT_CHARS = 200;
+
+/**
+ * How much retrieved documentation a question carries (the `ai.ask.retrieval`
+ * config). Every field falls back to the built-in default, so a partial object
+ * only changes what it names. Injected characters dominate time-to-first-token
+ * on a self-hosted backend, and the three knobs aren't interchangeable: the
+ * budget caps the total, `excerptChars` decides how deep into one long page the
+ * excerpt reaches, and `maxResults` decides how many pages retrieval adds (the
+ * page the reader is viewing is injected on top of them).
+ */
+export interface AskRetrievalOptions {
+  /** Overall cap on injected documentation characters. Defaults to `10000`. */
+  contextBudget?: number;
+  /** Characters kept per injected excerpt. Defaults to `2000`. */
+  excerptChars?: number;
+  /**
+   * Documents retrieved per question. Defaults to `6`. The current page is
+   * injected in addition when it isn't among the hits.
+   */
+  maxResults?: number;
+}
 /** Chars of lead-in kept before the matched region, for heading/sentence context. */
 const EXCERPT_LEAD = 160;
 
@@ -176,13 +204,14 @@ export const relevantExcerpt = (
     return `${prefix}${slice}${suffix}`;
   };
 
-  const lower = trimmed.toLowerCase();
+  // Case-insensitive matching via regex rather than `indexOf` on a lowercased
+  // copy: length-changing case mappings (Turkish İ → "i" + U+0307) would shift
+  // every index in the copy, sliding the excerpt window off the match. Terms
+  // come from TERM (letters, marks and digits only), so no regex escaping.
   const positions: number[] = [];
   for (const term of queryTerms(query)) {
-    let idx = lower.indexOf(term);
-    while (idx !== -1) {
-      positions.push(idx);
-      idx = lower.indexOf(term, idx + term.length);
+    for (const match of trimmed.matchAll(new RegExp(term, "giu"))) {
+      positions.push(match.index);
     }
   }
   // No query terms hit this doc — nothing to center on, so keep the head.
@@ -232,10 +261,13 @@ export const relevantExcerpt = (
  * the base instruction rather than replacing it: the base carries the
  * functional contract (answer only from the excerpts, cite pages as Markdown
  * links) that the panel's citation rendering depends on.
+ *
+ * `options.retrieval` (the `ai.ask.retrieval` config) sizes how much
+ * documentation each question carries; omitted fields keep today's defaults.
  */
 export const createAskContext = (
   data: AskData,
-  options?: { instructions?: string }
+  options?: { instructions?: string; retrieval?: AskRetrievalOptions }
 ): ((
   messages: AskMessage[],
   page?: AskPage
@@ -250,6 +282,9 @@ export const createAskContext = (
   const instruction = options?.instructions
     ? `${BASE_INSTRUCTION}\n\n${options.instructions}`
     : BASE_INSTRUCTION;
+  const maxResults = options?.retrieval?.maxResults ?? MAX_RESULTS;
+  const excerptChars = options?.retrieval?.excerptChars ?? EXCERPT_CHARS;
+  const contextBudget = options?.retrieval?.contextBudget ?? CONTEXT_BUDGET;
 
   return async (messages, page) => {
     const list = Array.isArray(messages) ? messages : [];
@@ -263,22 +298,27 @@ export const createAskContext = (
       ? byRoute.get(normalizeRoute(page.path))
       : undefined;
     const db = await index();
-    const hits = await queryOramaIndex(db, query, MAX_RESULTS, {
+    const hits = await queryOramaIndex(db, query, maxResults, {
       locale: current?.locale || undefined,
     });
 
     const seen = new Set<string>();
     const sections: string[] = [];
-    let budget = CONTEXT_BUDGET;
+    let budget = contextBudget;
     const push = (doc: OramaDoc, label: string) => {
       if (seen.has(doc.route) || budget <= 0) {
         return;
       }
+      // Skip a page that would be cut to a junk fragment: its excerpt is only
+      // useful when it either fits whole or gets at least the minimum window.
+      if (budget < MIN_EXCERPT_CHARS && doc.content.trim().length > budget) {
+        return;
+      }
       seen.add(doc.route);
       const body = relevantExcerpt(
         doc.content,
         query,
-        Math.min(EXCERPT_CHARS, budget)
+        Math.min(excerptChars, budget)
       );
       budget -= body.length;
       sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);

package/src/ai/mcp/data.ts

@@ -37,8 +37,9 @@ export interface McpData {
   base: string;
   /**
    * The site's `i18n.defaultLocale`, when i18n is configured. Selects a
-   * word-segmenting Orama tokenizer for languages written without spaces, so
-   * `search_docs` can match CJK/Thai content.
+   * word-segmenting Orama tokenizer for every non-Latin script, so
+   * `search_docs` can match CJK, Cyrillic, Greek, Hebrew, or Devanagari
+   * content.
    */
   defaultLocale?: string;
   /**

package/src/ai/mcp/server.ts

@@ -311,8 +311,9 @@ export type OramaIndexProvider = () => Promise<
 
 /**
  * Memoize the search index so every server built from a snapshot shares it.
- * `locale` is the snapshot's `defaultLocale`, forwarded so unspaced scripts
- * (Japanese, Chinese, Korean, Thai) get a word-segmenting tokenizer.
+ * `locale` is the snapshot's `defaultLocale`, forwarded so non-Latin scripts
+ * (Japanese and Chinese, but equally Cyrillic, Greek, Hebrew, Devanagari…)
+ * get a word-segmenting tokenizer.
  */
 export const createIndexProvider = (
   documents: OramaDoc[],

package/src/astro/generate.ts

@@ -50,6 +50,7 @@ import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
+import type { OpenApiData } from "../openapi/model.ts";
 import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
@@ -94,6 +95,7 @@ import {
   mixedbreadSearchEndpointTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
+  playgroundProxyTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
   runtimeDirWithin,
@@ -964,6 +966,13 @@ const FAVICON_CANDIDATES = [
   "icon.ico",
 ];
 
+/**
+ * Derive the `-dark` sibling of an icon filename (`icon.svg` → `icon-dark.svg`),
+ * inserting the suffix before the extension.
+ */
+const darkSibling = (name: string): string =>
+  name.replace(/\.(?=[^.]+$)/u, "-dark.");
+
 /** `<link type>` MIME for the favicon extensions we recognize. */
 const FAVICON_TYPES = new Map([
   ["ico", "image/x-icon"],
@@ -983,8 +992,19 @@ const faviconType = (name: string): string | undefined => {
 const inlineDataUri = (file: string, type: string): string =>
   `data:${type};base64,${readFileSync(file).toString("base64")}`;
 
-/** The bundled Blume favicon, inlined as a data URI so it needs no public file. */
+/**
+ * The bundled Blume favicon, inlined as a data URI so it needs no public file.
+ * The mark is dark, so it ships with a light-on-transparent dark-scheme variant —
+ * otherwise it disappears against dark browser chrome.
+ */
 const defaultFavicon = (): BlumeFavicon => ({
+  dark: {
+    href: inlineDataUri(
+      join(BLUME_SRC, "assets", "icon-dark.png"),
+      "image/png"
+    ),
+    type: "image/png",
+  },
   href: inlineDataUri(join(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png",
 });
@@ -1029,16 +1049,52 @@ const resolveIconFile = (
 
 /**
  * Resolve the site favicon by convention, falling back to the bundled Blume mark
- * when the project ships no `icon.*`/`favicon.*` file.
+ * when the project ships no `icon.*`/`favicon.*` file. The dark-scheme variant
+ * is anchored to the resolved icon: its `-dark` sibling (e.g. `icon.svg` →
+ * `icon-dark.svg`) in the same directory — never an unrelated `-dark` file, so a
+ * stale or foreign `favicon-dark.*` can't silently pair with a different mark.
+ * A `-dark` file with no light sibling is the site's only mark and is used for
+ * both schemes, mirroring how `resolveLogo` treats a single-variant image.
  */
-const resolveFavicon = (project: BlumeProject): BlumeFavicon =>
-  resolveIconFile(project, FAVICON_CANDIDATES) ?? defaultFavicon();
+const resolveFavicon = (project: BlumeProject): BlumeFavicon => {
+  const { root } = project.context;
+  for (const name of FAVICON_CANDIDATES) {
+    if (existsSync(join(root, "public", name))) {
+      const type = faviconType(name);
+      const sibling = darkSibling(name);
+      return existsSync(join(root, "public", sibling))
+        ? { dark: { href: `/${sibling}`, type }, href: `/${name}`, type }
+        : { href: `/${name}`, type };
+    }
+  }
+  for (const name of FAVICON_CANDIDATES) {
+    const file = join(root, name);
+    if (existsSync(file)) {
+      const type = faviconType(name);
+      const mime = type ?? "image/x-icon";
+      const siblingFile = join(root, darkSibling(name));
+      return existsSync(siblingFile)
+        ? {
+            dark: { href: inlineDataUri(siblingFile, mime), type },
+            href: inlineDataUri(file, mime),
+            type,
+          }
+        : { href: inlineDataUri(file, mime), type };
+    }
+  }
+  return (
+    resolveIconFile(project, FAVICON_CANDIDATES.map(darkSibling)) ??
+    defaultFavicon()
+  );
+};
 
 /**
  * Resolve the Apple touch icon by convention, or null when the project ships
  * none (unlike the favicon, there's no bundled default). Note: iOS ignores
  * `data:`-URI apple-touch-icons, so a `public/` file (served by URL) is the
  * reliable path; a root-level file is still inlined for symmetry with favicons.
+ * Deliberately no `-dark` sibling detection here: iOS ignores `media` on
+ * `apple-touch-icon` links, so a dark variant could never be served.
  */
 const resolveAppleIcon = (project: BlumeProject): BlumeFavicon | null =>
   resolveIconFile(project, APPLE_ICON_CANDIDATES);
@@ -1231,6 +1287,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         palette: config.seo.og.palette,
         site: resolveOgSite(config),
       },
+      openInChat: config.ai.openInChat,
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
@@ -1394,6 +1451,76 @@ const writeMcpFiles = async (
   ]);
 };
 
+/**
+ * Decide whether to generate the playground's built-in CORS proxy endpoint.
+ * Only the Blume renderer's playground with `proxy: true` needs it — a proxy
+ * URL string points at an external service, and `false` sends requests
+ * directly. Injected at `/_api-proxy` (rather than written under `pages/`)
+ * because Astro treats `_`-prefixed page files as private; the endpoint's own
+ * `prerender = false` export wins over the injection default.
+ */
+const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
+  enabled:
+    config.openapi.enabled &&
+    config.openapi.renderer === "blume" &&
+    config.openapi.playground.enabled &&
+    config.openapi.playground.proxy === true,
+  entrypoint: join(srcDir, "blume-openapi", "api-proxy.ts"),
+  pattern: "/_api-proxy",
+});
+
+/**
+ * The origins the built-in proxy is allowed to reach: one per absolute
+ * `servers[].url` across the parsed specs. This is the endpoint's whole trust
+ * boundary — the client sends the target as a query parameter, and a reader's
+ * custom base URL is not a documented server — so it is derived here, at build
+ * time, from the same documents the operation pages render.
+ *
+ * Relative (`/v1`) and templated (`{env}.api.example.com`) server URLs carry no
+ * origin to allow and are skipped; AsyncAPI documents declare `servers` as a
+ * map and contribute nothing (the proxy is OpenAPI-only).
+ */
+const specOrigins = (data: OpenApiData): string[] => {
+  const origins = new Set<string>();
+  for (const spec of Object.values(data)) {
+    // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
+    // the optional `servers` shape, and every access below re-checks it —
+    // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
+    const { servers } = spec.document as { servers?: { url?: string }[] };
+    for (const server of Array.isArray(servers) ? servers : []) {
+      const url = server.url ?? "";
+      // `new URL("https://{region}.api.example.com")` parses — the braces land
+      // in the hostname — so templated URLs need an explicit check or their
+      // junk literal becomes an allowlist entry no real request can match.
+      if (url.includes("{")) {
+        continue;
+      }
+      try {
+        origins.add(new URL(url).origin);
+      } catch {
+        // Not an absolute URL: nothing to allow.
+      }
+    }
+  }
+  return [...origins].toSorted();
+};
+
+/**
+ * The build-time diagnostic for a proxy whose allowlist came out empty. The
+ * allowlist comes solely from absolute `servers[].url` entries — relative and
+ * templated ones carry no origin — and with none at all the endpoint would
+ * 403 every playground send with nothing pointing the author at the spec.
+ */
+const proxyAllowlistWarnings = (
+  enabled: boolean,
+  origins: string[]
+): string[] =>
+  enabled && origins.length === 0
+    ? [
+        "openapi.playground.proxy is enabled, but no spec declares an absolute servers[].url (relative and templated URLs carry no origin), so the proxy's allowlist is empty and it will refuse every request. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.",
+      ]
+    : [];
+
 /**
  * Write the Ask AI endpoint and, unless the backend runs its own retrieval
  * (Inkeep), the grounding snapshot the endpoint queries at request time. A no-op
@@ -1417,7 +1544,10 @@ const writeAskFiles = async (
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
-    askEndpointTemplate(resolveAskBackend(ask), grounded, ask.instructions)
+    askEndpointTemplate(resolveAskBackend(ask), grounded, {
+      instructions: ask.instructions,
+      retrieval: ask.retrieval,
+    })
   );
 };
 
@@ -1635,6 +1765,25 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
+  // The parsed OpenAPI specs behind the `blume:openapi` alias, also the source
+  // of the proxy's origin allowlist below. The source parsed them during the
+  // scan, so reading them here is free.
+  const openApiSource = project.sources.find(isOpenApiSource);
+  const openApiData = openApiSource ? openApiSource.openApiData() : {};
+
+  // The playground's built-in CORS proxy rides the same injection path as the
+  // MCP discovery docs; the endpoint itself opts out of prerendering.
+  const playgroundProxy = planPlaygroundProxy(config, srcDir);
+  if (playgroundProxy.enabled) {
+    pages.push({
+      entrypoint: playgroundProxy.entrypoint,
+      pattern: playgroundProxy.pattern,
+    });
+  }
+  // Computed once: the endpoint template bakes it in below, and an empty list
+  // is worth a diagnostic — the proxy would refuse every request it gets.
+  const proxyOrigins = specOrigins(openApiData);
+
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
   // actually feeds it. An all-staged project (openapi/notion/…) has only staged
@@ -1780,6 +1929,9 @@ export const generateRuntime = async (
     ),
     writeAskFiles(project, srcDir, write),
     writeMcpFiles(project, mcp, write),
+    playgroundProxy.enabled
+      ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
+      : Promise.resolve(false),
   ]);
 
   if (config.seo.og.enabled) {
@@ -1895,6 +2047,7 @@ export const generateRuntime = async (
   // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
+    ...proxyAllowlistWarnings(playgroundProxy.enabled, proxyOrigins),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
@@ -1961,20 +2114,16 @@ export const generateRuntime = async (
     );
   }
 
-  // The parsed OpenAPI specs behind the `blume:openapi` alias. Always written
-  // (even as `{}`) so the alias resolves whether or not a reference is enabled;
-  // the source parsed the specs during the scan, so this is just serialization.
-  const openApiSource = project.sources.find(isOpenApiSource);
+  // `openapi.json` (the `blume:openapi` alias) is always written — even as `{}`
+  // — so the alias resolves whether or not a reference is enabled; the specs
+  // were parsed during the scan, so this is just serialization.
   // These write to distinct trees and never read one another, so they batch.
   // `data.json`/`openapi.json` and the manifest are not "structural" for Astro;
   // they hot-reload. `writeStagedContent` owns the `.blume/content` tree (its
   // own pruning), outside `.blume/src`, so a removed remote entry doesn't linger.
   await Promise.all([
     write(join(srcDir, "generated", "data.json"), buildRuntimeData(project)),
-    write(
-      openapiPath,
-      `${JSON.stringify(openApiSource ? openApiSource.openApiData() : {})}\n`
-    ),
+    write(openapiPath, `${JSON.stringify(openApiData)}\n`),
     write(
       join(out, "blume.manifest.json"),
       `${JSON.stringify(project.manifest, null, 2)}\n`

package/src/astro/templates.ts

@@ -3,6 +3,7 @@ import { pathToFileURL } from "node:url";
 
 import { dirname, isAbsolute, join, relative } from "pathe";
 
+import type { AskRetrievalOptions } from "../ai/ask-context.ts";
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
@@ -406,6 +407,11 @@ const resolveOptimizeDeps = (options: {
   const optimizeDepsInclude = [
     "blume > mermaid",
     "blume > epub-gen-memory/bundle",
+    // Astro's own client-router/prefetch virtual modules are deliberately NOT
+    // forced in here: they read Vite `define`-injected constants
+    // (__PREFETCH_PREFETCH_ALL__ and friends) that a pre-bundled copy loses,
+    // throwing ReferenceError on every page. Astro manages their optimization
+    // itself, without a mid-session reload.
     ...(options.needsReact && options.reactCompilerPath
       ? ["react/compiler-runtime"]
       : []),
@@ -694,10 +700,10 @@ ${userConfigSetup}export default defineConfig({
     },
   },
   devToolbar: { enabled: false },
-  // Navigations are full document loads (no client router), so the next page's
-  // HTML is fetched on hover/viewport to hide the request latency behind the
-  // user's intent. Pairs with the cross-document view-transition rule in the
-  // theme sheet, which smooths the swap itself.
+  // The layouts render Astro's <ClientRouter />, and its in-place swaps read
+  // from the prefetch cache — fetching every link on hover/viewport hides the
+  // request latency behind the user's intent, so most navigations swap
+  // instantly.
   prefetch: { prefetchAll: true },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
@@ -892,17 +898,30 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 const ASK_FALLBACK_PROMPT =
   "You are a helpful documentation assistant. Answer using the project's documentation.";
 
+/** The `ai.ask` values the generated endpoint has to carry with it. */
+export interface AskEndpointOptions {
+  /** `ai.ask.instructions` — extra system-prompt text. */
+  instructions?: string;
+  /** `ai.ask.retrieval` — how much documentation each question carries. */
+  retrieval?: AskRetrievalOptions;
+}
+
 /**
  * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
- * `instructions` (the `ai.ask.instructions` config) is appended to the
+ *
+ * `options.instructions` (the `ai.ask.instructions` config) is appended to the
  * built-in prompt on every path: the grounded prompt via `createAskContext`,
- * and the plain fallback here.
+ * and the plain fallback here. `options.retrieval` (the `ai.ask.retrieval`
+ * config) is forwarded to `createAskContext` on the grounded path, where it
+ * sizes retrieval. Both travel in one options object so a new call site can't
+ * silently drop one of them.
  */
 export const askEndpointTemplate = (
   backend: AskBackend,
   grounded: boolean,
-  instructions?: string
+  options?: AskEndpointOptions
 ): string => {
+  const instructions = options?.instructions;
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
@@ -938,9 +957,15 @@ export const askEndpointTemplate = (
       'import { createAskContext } from "blume/ai/ask-context.ts";',
       'import askData from "../../generated/ask-data.json";'
     );
-    const groundOptions = instructions
-      ? `, { instructions: ${JSON.stringify(instructions)} }`
-      : "";
+    const groundFields: string[] = [];
+    if (instructions) {
+      groundFields.push(`instructions: ${JSON.stringify(instructions)}`);
+    }
+    if (options?.retrieval) {
+      groundFields.push(`retrieval: ${JSON.stringify(options.retrieval)}`);
+    }
+    const groundOptions =
+      groundFields.length > 0 ? `, { ${groundFields.join(", ")} }` : "";
     setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
   }
   // Validate the client-supplied body and cap its size. The endpoint is
@@ -1104,7 +1129,7 @@ const SEARCH_BASE_IMPORT =
 /**
  * A client that loads a static `blume-search.json` index (Orama, FlexSearch).
  * `locale` (Orama only) is the site's `i18n.defaultLocale`, which selects a
- * word-segmenting tokenizer for languages written without spaces.
+ * word-segmenting tokenizer for every non-Latin script.
  */
 const staticSearchClient = (module: string, locale?: string): string =>
   `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}${SEARCH_BASE_IMPORT}
@@ -1415,6 +1440,31 @@ export const ALL: APIRoute = ({ request }) => handler(request);
 `;
 };
 
+/**
+ * Generate the playground's CORS proxy endpoint
+ * (`.blume/src/blume-openapi/api-proxy.ts`), behind
+ * `openapi.playground.proxy: true`. A thin server-rendered wrapper around the
+ * shipped `createPlaygroundProxyHandler`; injected at `/_api-proxy` rather
+ * than written under `pages/` because Astro treats `_`-prefixed page files as
+ * private.
+ *
+ * `origins` — the origins of the servers the documented specs declare — is
+ * baked in as the handler's allowlist. It cannot come from the request or from
+ * client-side data: that is the whole trust boundary keeping the endpoint from
+ * being an open proxy onto the deployment's own network.
+ */
+export const playgroundProxyTemplate = (origins: string[]): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { createPlaygroundProxyHandler } from "blume/openapi/proxy.ts";
+
+export const prerender = false;
+
+const handler = createPlaygroundProxyHandler(${JSON.stringify(origins)});
+
+export const ALL: APIRoute = ({ request }) => handler(request);
+`;
+
 /** Generate a prerendered endpoint that serves a fixed JSON payload. */
 export const staticJsonEndpointTemplate = <Payload extends object>(
   payload: Payload
@@ -1956,6 +2006,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   feedback={data.config.feedback}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
+  openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}
   siteUrl={data.config.site}
@@ -2188,6 +2239,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   canonical={canonical}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
+  openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}
   siteUrl={data.config.site}

package/src/components/content/AccordionItem.astro

@@ -121,6 +121,10 @@ const accordionId = id ?? componentSlug(title);
     };
 
     window.addEventListener("hashchange", openHashAccordion);
+    // Client-router swaps replace the body with fresh server-rendered
+    // accordions (duplicate ids and all), so the dedupe + hash-open pass has
+    // to run again for each new page.
+    document.addEventListener("astro:after-swap", init);
     if (document.readyState === "loading") {
       document.addEventListener("DOMContentLoaded", init, { once: true });
     } else {