blume 1.5.0 → 1.5.2

package/docs/configuration/index.mdx

@@ -140,6 +140,18 @@ my-docs/
 
 SVG wins over PNG over ICO when several are present, and a file in `public/` is preferred over one at the root. If Blume finds no icon, it falls back to its own mark.
 
+A dark mark disappears against dark browser chrome, so you can ship a second file for dark mode. Add a `-dark` sibling of your icon file — the same name and directory, with `-dark` before the extension (`icon.png` → `icon-dark.png`) — and Blume emits both icons behind a `prefers-color-scheme` media query, plus a plain light tag for browsers and crawlers that ignore media queries on icons:
+
+```
+my-docs/
+├─ blume.config.ts
+├─ icon.png          ← light mode
+├─ icon-dark.png     ← dark mode
+└─ docs/
+```
+
+Only the sibling of the icon Blume picked is used — a `-dark` file with a different name stays ignored, so an unrelated file can't pair with your mark by accident. The dark file is optional; with only one icon, Blume emits a single tag as before. Blume's own fallback mark ships both variants.
+
 ### Apple touch icon
 
 The icon iOS uses when someone adds your site to their home screen is detected the same way. Drop an `apple-icon` file (`.png`, `.jpg`, or `.jpeg`) — or an `apple-touch-icon.png`, the name most favicon generators emit — in your project root or `public/` directory and Blume wires up `<link rel="apple-touch-icon">` for you. There's no default; if no file is found, no tag is emitted.
@@ -151,7 +163,7 @@ my-docs/
 └─ docs/
 ```
 
-Put the file in `public/` rather than the project root: iOS ignores the inlined data URI Blume uses for a root-level icon, so only a `public/` file (served at `/apple-icon.png`) reliably reaches the home screen.
+Put the file in `public/` rather than the project root: iOS ignores the inlined data URI Blume uses for a root-level icon, so only a `public/` file (served at `/apple-icon.png`) reliably reaches the home screen. Unlike the favicon, there's no `-dark` sibling here — iOS ignores media queries on home-screen icons, so a dark variant could never be served.
 
 ### Banner
 
@@ -289,7 +301,7 @@ lastModified: true,
 | `{ type: "git" }` | Same as `true`, written explicitly. |
 | `{ type: "frontmatter" }` | Never run git — use only the `lastModified` frontmatter field. |
 
-The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time (avoid a shallow `--depth 1` checkout in CI). A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
+The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time. CI platforms usually check out a shallow clone, which silently drops most dates (the build warns with `BLUME_SHALLOW_GIT_HISTORY` when that happens): on Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable; with `actions/checkout`, set `fetch-depth: 0`. A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
 
 ```mdx page.mdx
 ---

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/configuration/theming.mdx

@@ -15,7 +15,7 @@ theme: {
   radius: "md",     // none | sm | md | lg
   mode: "system",   // system | light | dark
   fonts: {          // self-hosted Google Fonts
-    display: "inter-tight",
+    display: "inter",
     body: "inter",
     mono: "ibm-plex-mono",
   },
@@ -57,12 +57,14 @@ A toggle in the header always lets readers switch, and their choice is remembere
 - **`body`** — body text, UI, and prose
 - **`mono`** — code blocks and inline code
 
+Headings get display-grade letter-spacing (`-0.05em`) from the theme itself, so whatever you pick for `display` — including text families like the Inter default — reads correctly at heading sizes instead of depending on tracking built into the font.
+
 Each defaults to a curated Google Font, so Blume looks intentional out of the box:
 
 ```ts blume.config.ts lineNumbers
 theme: {
   fonts: {
-    display: "inter-tight",   // default
+    display: "inter",         // default
     body: "inter",            // default
     mono: "ibm-plex-mono",    // default
   },

package/docs/reference/cli.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: Every Blume command and flag explained in one place — init, dev, build, preview, add, sync, and eject — along with the options each one accepts.
+description: Every Blume command and flag explained in one place, along with the options each one accepts.
 ---
 
 ```bash
@@ -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.0",
+  "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";
@@ -61,7 +62,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
-import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
+import { buildFontsCss, configuredFonts } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.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",
@@ -1255,7 +1312,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     })),
     // CSS variables for Astro's <Font> component; matches the astro.config
     // `fonts:` entries derived from the same theme.fonts config.
-    fontCssVars: configuredCssVars(config.theme.fonts),
+    fontCssVars: configuredFonts(config.theme.fonts),
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
@@ -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,
+    })
   );
 };
 
@@ -1624,12 +1754,36 @@ export const generateRuntime = async (
   // private and filtered out anyway, but the intent is the user's pages.
   const ogRoutes = customOgRoutes(pages, config.title, config.seo.og.titles);
 
+  // Whether the generated `/changelog` index exists — shared by the OG endpoint
+  // (which adds the index's own card) and the page write below. Computed here,
+  // before the MCP discovery pages are appended, on the user's own pages.
+  const changelogIndex = hasGeneratedChangelog(project, pages);
+
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
   // normal (server-rendered) page written by `writeMcpFiles`.
   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
@@ -1775,17 +1929,20 @@ 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) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes, projectOgFonts(project))
+      ogEndpointTemplate(ogRoutes, projectOgFonts(project), changelogIndex)
     );
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1890,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,
@@ -1906,7 +2064,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceRoutes(config),
   ]);
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     navTargetRoutes.add("/changelog");
   }
   // Curated `search.popular` icons live outside the navigation model, so they
@@ -1956,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`