blume 2.2.2 → 2.2.4

package/docs/configuration/theming.mdx

@@ -14,6 +14,7 @@ theme: {
   accent: "teal",   // a named preset or any CSS color
   radius: "md",     // none | sm | md | lg
   mode: "system",   // system | light | dark
+  toggle: true,     // show the light/dark toggle
   fonts: {          // self-hosted Google Fonts
     display: "inter",
     body: "inter",
@@ -51,7 +52,18 @@ Text on an accent or action fill, like a button label or a step number, is white
 - **`system`** (default) — follow the reader's OS preference
 - **`light`** / **`dark`** — default to one scheme
 
-A toggle in the header always lets readers switch, and their choice is remembered across visits. Dark mode is applied with a `data-theme="dark"` attribute on the `<html>` element.
+A toggle in the header lets readers switch, and their choice is remembered across visits. Dark mode is applied with a `data-theme="dark"` attribute on the `<html>` element.
+
+To ship a single scheme, set `toggle: false`. The header drops the toggle, and every page renders in `mode`, even for readers who picked the other scheme before the toggle was removed:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  mode: "dark",
+  toggle: false,
+}
+```
+
+With `mode: "system"`, `toggle: false` follows each reader's OS setting and gives them no way to override it.
 
 ### Fonts
 

package/docs/content/frontmatter.mdx

@@ -23,7 +23,7 @@ Frontmatter is YAML, so quote a value that holds a colon followed by a space, li
     authors: {
       type: "string | string[] | object[]",
       description:
-        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Preserved as-is.",
+        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Credited as Person nodes in the page's JSON-LD; other fields are preserved as-is.",
     },
     slug: {
       type: "string",

package/docs/content/i18n.mdx

@@ -186,7 +186,7 @@ i18n: {
 Localized SEO is handled for you — no per-page metadata to write:
 
 - `<html lang>` and `dir` are set from the active locale.
-- `hreflang` alternates link every real translation of a page, plus an `x-default` pointing at the default locale.
+- `hreflang` alternates link every real translation of a page that search engines may index (a `noindex`, hidden, or canonical-elsewhere translation is left out), plus an `x-default` pointing at the default locale.
 - Canonical URLs are locale-correct, and JSON-LD carries `inLanguage`.
 
 Set [`deployment.site`](/docs/deployment) so these can be emitted as absolute URLs.

package/docs/content/sources/remote-mdx.mdx

@@ -35,7 +35,7 @@ mdxRemote({
 
 `include` (default `["**/*.{md,mdx}"]`) filters the files by their path under `path`, the way a `filesystem()` source's `include` does: a pattern starting with `!` excludes what it matches (`["**/*.mdx", "!drafts/**"]`). With `github`, the source lists the repository's whole tree at `ref` and keeps the files under `path`. If nothing is under `path` at that ref, the source reads no pages and warns with `BLUME_SOURCE_PATH_MISSING`. GitHub caps the listing (100,000 entries or 7 MB for the whole repository, whatever `path` is), and past it the source warns with `BLUME_SOURCE_TRUNCATED`: list the files with `url` and `files` instead.
 
-A relative link between remote files (`[Errors](./02-errors.mdx)`) lands on the page the linked file publishes at, with its ordering prefix dropped from the route, and `blume validate` checks it the same way.
+A relative link between remote files (`[Errors](./02-errors.mdx)`) lands on the page the linked file publishes at, with its ordering prefix dropped from the route. It does on the rendered page, in the page's [Markdown copy](/docs/discoverability/markdown#raw-markdown) and `llms-full.txt`, and in what the assistant reads, and `blume validate` checks it the same way.
 
 A private repo's token is read from the `GITHUB_TOKEN` environment variable. It is never inlined into your config or generated output, and it is only ever sent to GitHub's own hosts (`api.github.com`, `raw.githubusercontent.com`), never to a custom `url` base. A public repo works without it. With `github`, the adapter declares the variable, so `blume dev` and `blume build` warn `BLUME_MISSING_SECRET` when it's unset: the file listing goes through GitHub's API, which allows 60 unauthenticated requests an hour. A raw `url` reads files only, so nothing warns up front; when GitHub refuses a file with a 401, 403, or 404 while `GITHUB_TOKEN` is unset, the warning for the skipped file says the variable isn't set.
 

package/docs/discoverability/open-graph.mdx

@@ -3,7 +3,7 @@ title: Open Graph images
 description: Generated 1200×630 social cards for every page — branding, card layers, fonts for non-Latin scripts, and per-page overrides.
 ---
 
-Blume can render a 1200×630 social card for every page at build time — no headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay fast. On by default once [`deployment.site`](/docs/deployment) is set or auto-detected (the `og:image` URL has to be absolute to be useful to crawlers), and off otherwise. Set `enabled` to override that either way:
+Blume can render a 1200×630 social card for every page at build time — no headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay fast. On by default once [`deployment.site`](/docs/deployment) is set or auto-detected (the `og:image` URL has to be absolute to be useful to crawlers), and off otherwise or when a [default image](#default-image) replaces the cards. Set `enabled` to override that either way:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -11,6 +11,21 @@ seo: {
 }
 ```
 
+## Default image
+
+Set `seo.og.image` to share one image across every page instead of a generated card, or give each locale its own:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    image: { en: "/og/default-en.png", fr: "/og/default-fr.png" },
+    // Or image: "https://example.com/og/default.png"
+  },
+}
+```
+
+A page's `seo.image`, or a custom page's `ogImage` prop, wins over the default. A locale missing from the map takes the default locale's image. The default covers custom pages rendered with `PageLayout` and the generated changelog index too, so Blume stops generating cards once it's set, unless `enabled` is `true`. Root-relative paths resolve under the deployment base. Blume declares image dimensions only for generated cards. Whichever image a page ends up with also goes into its [JSON-LD](/docs/discoverability/structured-data) as the page's `image`.
+
 ## Brand the generated card
 
 Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.

package/docs/discoverability/sitemap-and-robots.mdx

@@ -15,6 +15,18 @@ seo: {
 }
 ```
 
+### Locale alternates
+
+Opt into alternate links on a multilingual site's sitemap:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  sitemap: { alternates: true },
+}
+```
+
+Each translated page lists its translations, itself included, as `xhtml:link` elements, plus an `x-default` link when the default locale has the page. These are the same `hreflang` links the page head carries: a `noindex`, hidden, or canonical-elsewhere translation is in neither. A page in fewer than two listed locales gets no alternate links. URLs include the deployment base. `sitemap: true` and `sitemap: {}` keep alternates off; `sitemap: false` turns the sitemap off.
+
 Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file you place in `public/`.
 
 ## Robots

package/docs/discoverability/structured-data.mdx

@@ -48,6 +48,50 @@ seo: {
 
 `software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.
 
+## Shared entity identifiers
+
+When docs live inside another site (`example.com/docs`), point at the entities that site already defines instead of defining them again:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  jsonLd: {
+    websiteId: "https://example.com/#website",
+    organizationId: "https://example.com/#organization",
+  },
+}
+```
+
+Every page names `websiteId` as its `isPartOf`, and Blume stops emitting its own WebSite node, whose name and URL would describe the docs instead of the site. Set `website: true` to emit it anyway under that id, or `website: false` to omit the docs' own WebSite node without sharing an id. `organizationId` becomes every page's publisher. With [`seo.organization`](#site-identity) also set, the Organization node uses that id and carries only the fields you configure: the docs' title and URL don't stand in for its name and URL. By default, Blume emits the WebSite node and uses the site URL plus `#website` and `#organization`. Identifiers must be absolute URLs, so they work without a site URL too.
+
+## Page author and publisher
+
+Reference existing entities on every page:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  jsonLd: {
+    author: { "@id": "https://example.com/#author" },
+    publisher: { "@id": "https://example.com/#publisher" },
+  },
+}
+```
+
+These references apply to the WebPage or article node, and `publisher` replaces the organization as its publisher. Blume doesn't define the entities they point at. A page's own [`authors`](/docs/content/frontmatter) front matter wins over `author`: each one is credited as a `Person`.
+
+## Publication date from Git
+
+Date pages by the commit that added their content file:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  datePublished: "git",
+}
+```
+
+Front matter `date` or `changelog.date` still wins. Git dates the rest, through the same `git log` as [`lastModified`](/docs/configuration#last-modified). Renames are followed only when the content is unchanged, so a new page never inherits the history of a similar one deleted in the same commit. Pages from non-filesystem sources and uncommitted files get no date from git. A shallow clone dates no page and warns instead, since its oldest commit is where the clone was cut. Fetch full history in CI (`VERCEL_DEEP_CLONE=true` on Vercel, `fetch-depth: 0` for `actions/checkout`).
+
+The resolved [Open Graph image](/docs/discoverability/open-graph) is also included as the page node's `image`, whether it comes from frontmatter, a site default, or a generated card.
+
 ## Custom pages
 
 A custom [`.astro` page](/docs/advanced/custom-pages) rendered through `PageLayout` emits the same graph, so a marketing home page isn't the one URL without structured data. A custom page has no content file to date, so pass `lastModified` to give it a `dateModified`. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with this setting, or `structuredDataEnabled={false}` to turn it off for that page alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",
@@ -36,7 +36,8 @@
     "docs",
     "skills",
     "AGENTS.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -116,7 +117,7 @@
     "@astrojs/mdx": "^8.0.2",
     "@astrojs/node": "^11.1.6",
     "@astrojs/react": "^7.0.0",
-    "@astrojs/vercel": "^11.0.11",
+    "@astrojs/vercel": "^11.0.14",
     "@clack/prompts": "^1.8.0",
     "@iconify-json/lucide": "^1.2.140",
     "@iconify/types": "^2.0.0",

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

@@ -87,7 +87,7 @@ Read `app/app.config.ts` (`app.config.ts` at the project root on Nuxt 3), `nuxt.
 | `toc.bottom.links` | `navigation.featured` (`to` → `href`). Report the move |
 | `navigation.sub` | `navigation.tabs` (see Navigation). `'aside'` anchors have no Blume form; report |
 | `docus.locale` (not `en`) | a one-locale `i18n` block |
-| `docus.colorMode` | `theme.mode`. Blume always shows the toggle; report |
+| `docus.colorMode` | `theme.mode`. A forced mode also takes `theme.toggle: false` |
 | `assistant.faqQuestions` | `ai.assistant.suggestions` (`[{ label }]`; flatten categories) |
 | `ui.colors.primary` | `theme.accent`. Nuxt UI paints shade 500 in light mode and 400 in dark: a Blume preset of the same name, else `{ light, dark }` with those Tailwind values. **Not declared means Docus's emerald:** the site turns Blume's default color unless you offer `theme.accent: "green"`; report it either way |
 | `--ui-radius: 0` in CSS | `theme.radius: "none"` |
@@ -275,7 +275,6 @@ Report each of these, and anything else you drop:
   - Nuxt UI overrides and theme CSS that doesn't map
   - a custom `seo.titleTemplate`, `seo.schema`, and the TOC title
   - logo extras, and socials with no Blume platform
-  - a forced color mode (the toggle stays)
   - `navigation.sub: 'aside'` anchors
   - a header button that showed only on the landing page (now site-wide)
 - **Navigation:** text-order sorting (`10.` before `2.`), and pages that sorted after a folder.

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

@@ -20,7 +20,7 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `themeConfig.navbar.items` (doc items) | `navigation.tabs` (for section links) |
 | `themeConfig.navbar.items` (external/utility links — Blog, Discord…) | **`navigation.actions`** (`[{ label, href }]`, plain header links) to keep them in the header, or **`navigation.featured`** (`{ label, href, icon? }`, pinned above the sidebar on every route) if they should survive on phones; the GitHub link → the `github` config instead (it renders in the footer) |
 | `themeConfig.navbar.items` (a `className`-styled button — "Get started", "Sign up") | **`navigation.cta`** (`{ label, href }`, the header's one filled button; a route the docs don't serve must be an absolute URL) |
-| `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`) |
+| `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`); `colorMode.disableSwitch: true` → `theme.toggle: false` |
 | `themeConfig.prism.theme` / `.darkTheme` | `markdown.code.theme: { light, dark }` (map Prism theme names to Shiki themes, e.g. `github`/`github-dark`) |
 | `themeConfig.metadata` / `themeConfig.image` | per-page `seo` frontmatter / `seo.og`; report what doesn't fit |
 | `url` + `baseUrl` | **`url` → `deployment.site`**, unless the target host is Vercel or Netlify, which Blume auto-detects (see SKILL.md — GitHub Pages, a common Docusaurus host, is not one of them); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |

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

@@ -48,7 +48,7 @@ Read the whole module and the helpers it imports (sidebars, nav, per-locale conf
 | `rewrites` | **move each file to the path its rewrite produced**, so the URL stays put (`slug` only where moving is impossible). VitePress relative links are already written against the rewritten paths |
 | `srcDir` / `srcExclude` | `content.root` / `content.exclude`, which adds to the defaults `**/_*` and `**/.*` |
 | `outDir`, `assetsDir`, `cacheDir`, `ignoreDeadLinks`, `metaChunk`, `mpa` | drop |
-| `appearance` | `'dark'`/`'force-dark'` → `theme.mode: "dark"`; `false` → `"light"`; `true`/`'force-auto'` → omit. Blume always shows the toggle: report a forced mode |
+| `appearance` | `'dark'` → `theme.mode: "dark"`; `'force-dark'` → `theme: { mode: "dark", toggle: false }`; `false` → `theme: { mode: "light", toggle: false }`; `'force-auto'` → `theme.toggle: false`; `true` → omit |
 | `lastUpdated: true` | `lastModified: "git"` |
 | `sitemap.hostname` | `deployment.site`, unless the host is Vercel or Netlify (auto-detected). `sitemap.transformItems` → drop |
 | `markdown.theme` | `markdown.code.theme: { light, dark }`; VitePress's default (`github-light`/`github-dark`) is Blume's, so omit it unless changed |
@@ -201,4 +201,4 @@ The old URL list is `<old build>/**/*.html` (or the live `sitemap.xml`). Blume s
 
 ## Dropped — report these
 
-`titleTemplate`, the footer `message` (and any link inside `copyright`), forced `appearance`, per-page `outline`/`aside`, one-sided `prev`/`next`, page-level toggles (`editLink`, `footer`, `navbar`, `pageClass`), `head` entries beyond meta tags and analytics, build hooks, Vite and custom markdown-it plugins, unsupported social links, line-number offsets and the site-wide switch, snippet regions and include ranges (now split files), copied out-of-root snippets, data-driven and unregistered theme components (and any content they hid), `VPTeamMembers`, data loaders and dynamic routes, hero styling, the DocSearch index (with its credentials), old-site anchors that were already broken (and any left unpinned under `--only-linked`), version-dropdown links, and `::: note`/`important`/`caution` text that 1.x showed literally.
+`titleTemplate`, the footer `message` (and any link inside `copyright`), per-page `outline`/`aside`, one-sided `prev`/`next`, page-level toggles (`editLink`, `footer`, `navbar`, `pageClass`), `head` entries beyond meta tags and analytics, build hooks, Vite and custom markdown-it plugins, unsupported social links, line-number offsets and the site-wide switch, snippet regions and include ranges (now split files), copied out-of-root snippets, data-driven and unregistered theme components (and any content they hid), `VPTeamMembers`, data loaders and dynamic routes, hero styling, the DocSearch index (with its credentials), old-site anchors that were already broken (and any left unpinned under `--only-linked`), version-dropdown links, and `::: note`/`important`/`caution` text that 1.x showed literally.

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

@@ -70,7 +70,7 @@ Read the whole config, including the modules it imports. VuePress sites often ke
 | `nextLinks: false` **and** `prevLinks: false` (v1) | `pagination: false` on every page: there's no site-wide switch. Only one of them → drop (report) |
 | `search: false` | `search: false` |
 | `algolia` (`apiKey`, `indexName`, `appId`), in `themeConfig` or, in v1, any `themeConfig.locales[path]` | omit `search` (Orama) and report the credentials. A v1 `algolia` block is almost always **DocSearch**: Algolia's crawler fills the index (the app is `BH4D9OD16A` when `appId` is missing, and `algoliaOptions.facetFilters` often marks a shared index). Its records aren't Blume's, and Blume's sync, given an admin key, replaces the whole index on every build. Never point `algolia()` at it; a new index of your own is a separate opt-in |
-| **v2** `colorMode: 'dark'` / `'light'` | `theme.mode`. `colorModeSwitch: false` → report: Blume always shows the toggle |
+| **v2** `colorMode: 'dark'` / `'light'` | `theme.mode`. `colorModeSwitch: false` → `theme.toggle: false` |
 | **v2** `hostname` | `deployment.site`, unless the target host is Vercel or Netlify |
 | `locales` | see "i18n" |
 | `smoothScroll`, `searchMaxSuggestions`, `searchPlaceholder`, `repoLabel`, `editLinkText`, **v2** `contributors`, `externalLinkIcon`, `home`, `notFound`, `backToHome`, and the other UI labels | drop. A translated UI string → `i18n.ui` |

package/src/ai/ask-context.ts

@@ -1,8 +1,14 @@
 import { normalizeRoute } from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
+import {
+  accentInsensitive,
+  foldLatinTerm,
+  stripSoftHyphens,
+} from "../search/fold.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
+import { linkText } from "./link-text.ts";
 
 /** A chat message as posted by the assistant island (`{ role, content }`). */
 export interface AskMessage {
@@ -47,7 +53,7 @@ const EXCERPT_CHARS = 2000;
 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
+ * 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.
  */
@@ -196,7 +202,7 @@ const hasSegmenter = (
 ): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
 
 const segmentQuery = (query: string): string[] => {
-  const lowered = query.normalize("NFC").toLowerCase();
+  const lowered = stripSoftHyphens(query).normalize("NFC").toLowerCase();
   if (!hasSegmenter(Intl.Segmenter)) {
     return lowered.match(TERM) ?? [];
   }
@@ -210,9 +216,15 @@ const segmentQuery = (query: string): string[] => {
   return pieces;
 };
 
-/** Lowercase word tokens of `text`, cut at the same boundaries as a query. */
+/**
+ * Lowercase word tokens of `text`, cut at the same boundaries as a query.
+ * Latin words fold the way the search index folds them, so the section a page
+ * was retrieved for (Prüfung, for the question `prufung`) is the one excerpted.
+ */
 const tokenize = (text: string): string[] =>
-  segmentQuery(text).flatMap((piece) => piece.match(TERM) ?? []);
+  segmentQuery(text).flatMap((piece) =>
+    (piece.match(TERM) ?? []).map((term) => foldLatinTerm(term))
+  );
 
 /** Distinct, meaningful lowercase terms from a query (drops stopwords). */
 const queryTerms = (query: string): string[] =>
@@ -222,11 +234,35 @@ const queryTerms = (query: string): string[] =>
 
 /**
  * The grounding preamble. The model is told to answer strictly from the injected
- * excerpts and to cite the pages it used as Markdown links (each excerpt is
- * headed by `## Title (/route)`), so citations render as real links in the panel.
+ * excerpts and to cite the pages it used as Markdown links, so citations render
+ * as real links in the panel. Each excerpt is headed by the very link to cite
+ * (`## [Title](/route)`), so a model that copies the heading copies a link.
  */
 const BASE_INSTRUCTION =
-  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt is headed by its page as `## Page Title (/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from, and write every citation as a Markdown link to that page using its route, e.g. [Page Title](/route).";
+  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt opens with a heading that links to its page, `## [Page Title](/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from with the link in the heading that opens their excerpt, written exactly as it is there: [Page Title](/route).";
+
+/** `encodeURIComponent` leaves parentheses as they are, so they're mapped here. */
+const PARENTHESES = new Map([
+  ["(", "%28"],
+  [")", "%29"],
+]);
+
+/**
+ * An excerpt's heading: the Markdown link the model cites the page with. A
+ * bracket or backslash in the title, or whitespace or a parenthesis in the
+ * route, would break the link, and a `%` in the route would read back as an
+ * escape (`read_page` decodes them), so those are escaped; the rest of the
+ * route stays as the reader sees it (`/ja/ポイント`).
+ */
+export const excerptHeading = (
+  doc: Pick<OramaDoc, "route" | "title">
+): string => {
+  const target = doc.route.replaceAll(
+    /[%\s()]/gu,
+    (char) => PARENTHESES.get(char) ?? encodeURIComponent(char)
+  );
+  return `## [${linkText(doc.title)}](${target})`;
+};
 
 /**
  * Appended when the endpoint gives the model the docs tools (see
@@ -272,7 +308,7 @@ const isFollowUp = (message: string): boolean => {
 /**
  * The texts that retrieve for the latest question, in rank order.
  *
- * The question itself always leads, verbatim: Orama's own tokenizer and BM25
+ * The question itself always leads, verbatim: the index's tokenizer and BM25
  * weighting see the whole sentence (version numbers, single-character CJK
  * words, `--flags`, and the bigrams a ja/zh index depends on all survive), and
  * a short question that names its subject ("Does it support i18n?") is never
@@ -350,13 +386,15 @@ export const relevantExcerpt = (
     return `${prefix}${slice}${suffix}`;
   };
 
-  // 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.
+  // Case- and accent-insensitive matching via regex rather than `indexOf` on
+  // a folded copy: length-changing mappings (Turkish İ → "i" + U+0307, ß →
+  // "ss") would shift every index in the copy, sliding the excerpt window off
+  // the match.
   const positions: number[] = [];
   for (const term of queryTerms(query)) {
-    for (const match of trimmed.matchAll(new RegExp(term, "giu"))) {
+    for (const match of trimmed.matchAll(
+      new RegExp(accentInsensitive(term), "giu")
+    )) {
       positions.push(match.index);
     }
   }
@@ -770,7 +808,7 @@ export const createAskContext = (
         Math.min(excerptChars, budget)
       );
       budget -= body.length;
-      sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);
+      sections.push(`${excerptHeading(doc)}${label}\n${body}`);
     };
 
     if (current) {

package/src/ai/ask-data.ts

@@ -14,7 +14,10 @@ import type { AskData } from "./ask-context.ts";
  * from the docs instead of declining.
  * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
  * (web-only content removed, agents-only unwrapped) and components downlevel to
- * Markdown, both matching llms-full.txt.
+ * Markdown, both matching llms-full.txt. Its page links point at the pages
+ * they mean, as there, but as the routes this snapshot keys those pages by:
+ * without the `deployment.base`, like the excerpt headings, since the chat
+ * panel mounts every link it renders under the base.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {

package/src/ai/ask-tools.ts

@@ -3,7 +3,12 @@ import { jsonSchema, tool } from "ai";
 import { normalizeRoute } from "../core/base-path.ts";
 import { queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
-import { askIndex, readerScope, sectionExcerpt } from "./ask-context.ts";
+import {
+  askIndex,
+  excerptHeading,
+  readerScope,
+  sectionExcerpt,
+} from "./ask-context.ts";
 import type { AskData, AskPage, ReaderScope } from "./ask-context.ts";
 
 /**
@@ -37,7 +42,7 @@ const PAGE_CHARS = 20_000;
 
 /** A result block, headed the way the injected excerpts are, for citing. */
 const block = (doc: OramaDoc, body: string): string =>
-  `## ${doc.title} (${doc.route})\n${body}`;
+  `${excerptHeading(doc)}\n${body}`;
 
 /**
  * Search the docs for `query` within the reader's scope: the most relevant
@@ -66,7 +71,9 @@ export const searchDocs = async (
 
 /**
  * The route a model asked for, as the snapshot keys it: a full URL on the
- * site becomes its path, and a query string or fragment is dropped.
+ * site becomes its path, a query string or fragment is dropped, and
+ * percent-escapes are decoded (a cited route escapes whitespace,
+ * parentheses, and `%`; see `excerptHeading`).
  */
 const routeOf = (data: AskData, requested: string): string => {
   let path = requested.trim();
@@ -74,6 +81,11 @@ const routeOf = (data: AskData, requested: string): string => {
     path = path.slice(data.site.replace(/\/$/u, "").length) || "/";
   }
   path = path.replace(/[?#].*$/u, "");
+  try {
+    path = decodeURI(path);
+  } catch {
+    // Malformed percent sequence — look it up as written.
+  }
   return normalizeRoute(path.startsWith("/") ? path : `/${path}`);
 };
 
@@ -106,7 +118,7 @@ export const createAskTools = (data: AskData) => {
     return {
       read_page: tool({
         description:
-          "Read one documentation page in full, by its route (the path in parentheses after a page title, such as /docs/getting-started).",
+          "Read one documentation page in full, by its route (the link target in the heading that opens a page's excerpt, such as /docs/getting-started).",
         execute: ({ route }) => Promise.resolve(readPage(data, byRoute, route)),
         inputSchema: jsonSchema<{ route: string }>({
           additionalProperties: false,
@@ -122,7 +134,7 @@ export const createAskTools = (data: AskData) => {
       }),
       search_docs: tool({
         description:
-          "Search this project's documentation. Returns the most relevant excerpt of each matching page, headed by its title and route.",
+          "Search this project's documentation. Returns the most relevant excerpt of each matching page, headed by a Markdown link to the page.",
         execute: ({ query }) => searchDocs(data, scope, query),
         inputSchema: jsonSchema<{ query: string }>({
           additionalProperties: false,

package/src/ai/link-text.ts

@@ -0,0 +1,6 @@
+/**
+ * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
+ * — closes or nests the text early, and the line stops being a link.
+ */
+export const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);

package/src/ai/llms.ts

@@ -13,6 +13,7 @@ import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
 import { downlevelComponents } from "./component-markdown.ts";
+import { linkText } from "./link-text.ts";
 import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
 import {
@@ -33,13 +34,6 @@ const pageUrl = (route: string, site?: string, base = ""): string => {
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
-/**
- * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
- * — closes or nests the text early, and the line stops being a link.
- */
-const linkText = (title: string): string =>
-  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
-
 /** Inputs only the build has: the published skills, collected once per build. */
 export interface LlmsIndexOptions {
   /**

package/src/ai/markdown.ts

@@ -7,7 +7,7 @@ import { discoverPages, discoverPagesSync } from "../core/custom-pages.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
-import type { RouteManifestEntry } from "../core/types.ts";
+import type { PageRecord, RouteManifestEntry } from "../core/types.ts";
 import { advertisedConfig, servesMcp } from "./agent-surface.ts";
 import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
@@ -64,8 +64,10 @@ export const buildRawMarkdown = async (
   const components = projectComponentSerializers(project);
   const rewriteLinks = relativeLinkRewriter(project);
 
-  const readRoute = async (route: RouteManifestEntry): Promise<string> => {
-    const page = pageById.get(route.id);
+  const readRoute = async (
+    route: RouteManifestEntry,
+    page: PageRecord | undefined
+  ): Promise<string> => {
     if (page) {
       return await readExpandedEntryText(project, page);
     }
@@ -74,7 +76,8 @@ export const buildRawMarkdown = async (
 
   const entries = await Promise.all(
     project.manifest.routes.map(async (route) => {
-      let text = await readRoute(route);
+      const page = pageById.get(route.id);
+      let text = await readRoute(route, page);
       if (route.sourcePath) {
         text = rewriteRelativeAssets({
           deployBase: project.config.deployment.options.base,
@@ -87,6 +90,7 @@ export const buildRawMarkdown = async (
       // agent fetched resolves it to, and `/install` gains the base and the
       // page's locale the rendered link has — remote content included.
       text = rewriteLinks(text, {
+        entryId: page?.entryId,
         route: route.path,
         sourcePath: route.sourcePath,
       });