blume 1.6.4 → 1.6.6

package/dist/types/ai/ask-context.d.ts

@@ -55,6 +55,31 @@ export interface AskRetrievalOptions {
  * Exported for testing; {@link createAskContext} is the runtime entry point.
  */
 export declare const relevantExcerpt: (content: string, query: string, max: number) => string;
+interface PageSection {
+    /** Word tokens of the section's heading line, or none when it has no heading. */
+    headingWords: string[];
+    /** Position in the page, for source-order output and omission markers. */
+    index: number;
+    text: string;
+    /** The section's word tokens, cut once so scoring is a prefix test. */
+    words: string[];
+}
+/** A page split into sections once, so per-request scoring never re-tokenizes. */
+export interface ParsedPage {
+    sections: PageSection[];
+    /** NFC-normalized, LF-only, trimmed page text; excerpts slice from it. */
+    text: string;
+}
+/**
+ * Split a page at its `##`+ headings (outside code fences). The text above the
+ * first heading is the page's own lead-in and is a section like any other.
+ * Line endings are folded to LF first so a CRLF checkout splits and matches the
+ * same way as an LF one. Exported for testing; {@link createAskContext}
+ * parses each page once and caches it across requests.
+ */
+export declare const parsePage: (content: string) => ParsedPage;
+/** {@link excerptPage} over a page parsed on the spot. Exported for testing. */
+export declare const sectionExcerpt: (content: string, query: string, max: number) => string;
 /**
  * Build the request-time grounding function for the Ask AI endpoint.
  *
@@ -76,3 +101,4 @@ export declare const createAskContext: (data: AskData, options?: {
     instructions?: string;
     retrieval?: AskRetrievalOptions;
 }) => ((messages: AskMessage[], page?: AskPage) => Promise<string | undefined>);
+export {};

package/dist/types/core/code-fences.d.ts

@@ -0,0 +1,11 @@
+/** The open fence's delimiter char and run length, or null outside one. */
+export type FenceState = {
+    delimiter: "`" | "~";
+    length: number;
+} | null;
+/**
+ * Advance the fenced-code state for one line: an opening fence records its
+ * delimiter and run length, only a bare run of the same character at least as
+ * long closes it (CommonMark), and any other line leaves the state untouched.
+ */
+export declare const nextFenceState: (line: string, fence: FenceState) => FenceState;

package/dist/types/core/config-input.d.ts

@@ -789,6 +789,16 @@ export interface AnalyticsScript {
 }
 /** Analytics providers. Configure one, several, or none. */
 export interface AnalyticsConfig {
+    /**
+     * Cloudflare Web Analytics, for a site Cloudflare doesn't proxy (manual
+     * setup). Not needed on a proxied zone with automatic RUM enabled — that
+     * injects the beacon at the edge, and configuring it here too would count
+     * every pageview twice.
+     */
+    cloudflare?: {
+        /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
+        token: string;
+    };
     /** PostHog product analytics. */
     posthog?: {
         /** API host (for self-hosted / EU). Defaults to PostHog cloud. */

package/dist/types/core/package-root.d.ts

@@ -11,7 +11,7 @@ export declare const findPackageRoot: (start: string) => string;
  * Anchoring here — rather than at a fixed offset from `import.meta` — keeps the
  * package's own `src/`, assets, and `node_modules` locatable whether the code
  * runs from source under Bun (`src/...`) or from the published, bundled CLI
- * (`dist/cli/index.js`). The two layouts sit at different depths, so a relative
+ * (`dist/cli/*.js`). The two layouts sit at different depths, so a relative
  * `../..` resolves to different places; locating `package.json` does not.
  */
 export declare const packageRoot: () => string;

package/dist/types/core/schema.d.ts

@@ -146,6 +146,76 @@ export declare const pageMetaSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PageMeta = z.infer<typeof pageMetaBaseSchema>;
 export type PageMetaInput = z.input<typeof pageMetaBaseSchema>;
+/**
+ * The page schema as the generated content collections declare it, so
+ * `entry.data` is typed and normalized (dates as ISO strings, X handles with
+ * their `@`) the same way the scan's `PageMeta` is. Two deliberate loosenings
+ * over {@link pageMetaSchema}: custom keys (`frontmatter.extend`, per-type
+ * maps) pass through instead of failing the strict parse, and a page the
+ * strict parse rejects resolves to the empty defaults instead of throwing.
+ * The scan has already dropped such a page with a `BLUME_FRONTMATTER_INVALID`
+ * diagnostic — Blume continues without it unless `--strict` — so the
+ * collection must not turn that dropped page into a failed content sync.
+ */
+export declare const pageCollectionSchema: z.ZodCatch<z.ZodObject<{
+    ai: z.ZodPrefault<z.ZodObject<{
+        exclude: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    authors: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodUnknown>>]>>]>>;
+    changelog: z.ZodOptional<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    date: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+    deprecated: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    draft: z.ZodDefault<z.ZodBoolean>;
+    hidden: z.ZodDefault<z.ZodBoolean>;
+    icon: z.ZodOptional<z.ZodString>;
+    lastModified: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>, z.ZodTransform<string, string | Date>>>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    search: z.ZodPrefault<z.ZodObject<{
+        boost: z.ZodOptional<z.ZodNumber>;
+        exclude: z.ZodDefault<z.ZodBoolean>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    seo: z.ZodPrefault<z.ZodObject<{
+        canonical: z.ZodOptional<z.ZodURL>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        noindex: z.ZodDefault<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+        x: z.ZodOptional<z.ZodObject<{
+            creator: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    sidebar: z.ZodPrefault<z.ZodObject<{
+        badge: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodEnum<{
+            flat: "flat";
+            group: "group";
+            page: "page";
+        }>>;
+        hidden: z.ZodDefault<z.ZodBoolean>;
+        icon: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    slug: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>;
 export declare const folderMetaSchema: z.ZodObject<{
     collapsed: z.ZodOptional<z.ZodBoolean>;
     display: z.ZodOptional<z.ZodEnum<{
@@ -561,6 +631,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         webmcp: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     analytics: z.ZodOptional<z.ZodObject<{
+        cloudflare: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+        }, z.core.$strict>>;
         posthog: z.ZodOptional<z.ZodObject<{
             host: z.ZodOptional<z.ZodString>;
             key: z.ZodString;
@@ -733,10 +806,10 @@ export declare const blumeConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
     deployment: z.ZodPrefault<z.ZodObject<{
         adapter: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            cloudflare: "cloudflare";
             vercel: "vercel";
             node: "node";
             netlify: "netlify";
-            cloudflare: "cloudflare";
         }>>>;
         base: z.ZodOptional<z.ZodString>;
         output: z.ZodDefault<z.ZodEnum<{

package/docs/02-deployment.mdx

@@ -101,7 +101,7 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
 
-On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path.
+On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/discoverability/markdown#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path. That Worker also answers the prerendered per-page JSON documents (`/api/docs/pages/{route}.json`) from the asset binding when a request for one reaches it, because Astro would otherwise route it to the `/api/` catch-all.
 
 :::note
 Server features have their own configuration — for example, Ask AI needs a model API key. See the [Ask AI guide](/docs/configuration/ask-ai) for setup.

package/docs/configuration/analytics.mdx

@@ -1,9 +1,9 @@
 ---
 title: Analytics
-description: First-party web analytics — Vercel Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
+description: First-party web analytics — Vercel Web Analytics, Cloudflare Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
 ---
 
-Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.
+Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics, Cloudflare Web Analytics, and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.
 
 Analytics loads in **production builds only**. The scripts are emitted by `blume build`, never by `blume dev`, so local traffic never reaches your dashboards and you don't need a separate "development" project.
 
@@ -23,6 +23,24 @@ analytics: {
 
 No keys are needed — the script reports to the project it's deployed under. This only collects data on Vercel deployments, where the `/_vercel/insights` endpoint exists.
 
+## Cloudflare Web Analytics
+
+[Cloudflare Web Analytics](https://developers.cloudflare.com/web-analytics/) has two setups, and only one of them needs config.
+
+**Proxied zone (automatic setup).** If Cloudflare serves your site — a Worker with a custom domain, Pages, or any zone with the orange cloud on — enable Web Analytics for the zone in the Cloudflare dashboard and stop there. Cloudflare injects the beacon at the edge, so leave `analytics.cloudflare` unset; configuring it as well would count every pageview twice.
+
+**Any other host (manual setup).** For a site Cloudflare doesn't proxy, add the site under Web Analytics in the dashboard, copy the token out of the JS snippet it gives you (the `token` inside `data-cf-beacon`), and pass it here. Blume renders the same beacon tag the snippet does.
+
+```ts blume.config.ts lineNumbers
+analytics: {
+  cloudflare: {
+    token: "0123456789abcdef0123456789abcdef",
+  },
+}
+```
+
+The token is safe to ship to the browser — it only identifies the site. The beacon tracks history changes on its own, so client-router navigations count without any extra wiring.
+
 ## PostHog
 
 Provide your **project API key** to add [PostHog](https://posthog.com). The host defaults to PostHog Cloud US; set `host` for EU Cloud (`https://eu.i.posthog.com`) or a self-hosted instance.
@@ -72,6 +90,7 @@ analytics: {
 | Option | Default | Description |
 | --- | --- | --- |
 | `vercel` | `false` | Add Vercel Web Analytics (Vercel deployments only). |
+| `cloudflare.token` | — | Cloudflare Web Analytics site token (manual setup). Enables the beacon when set. |
 | `posthog.key` | — | PostHog project API key. Enables PostHog when set. |
 | `posthog.host` | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted). |
 | `scripts[].src` | — | External script URL. Mutually exclusive with `content`. |

package/docs/configuration/ask-ai.mdx

@@ -170,7 +170,7 @@ Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to poin
 **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
 :::
 
-Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
+Keys are read through Astro's [`getSecret()`](https://docs.astro.build/en/guides/environment-variables/#retrieving-secrets-programmatically), so each adapter supplies them its own way: environment variables on Node, Vercel, and Netlify, and the Worker's [bindings](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) on Cloudflare. Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
 ## Rate limiting
 

package/docs/configuration/customization.mdx

@@ -182,13 +182,6 @@ blume eject --yes
 
 Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.
 
-### What eject leaves behind
+### What eject keeps
 
-After ejecting, your `build` script runs plain `astro build` — the site itself builds the same, but the artifacts `blume build` layered on top are no longer produced. The eject command warns about the ones your config actually uses. To keep them:
-
-- **Pagefind search index** — with `search.provider: "pagefind"`, the search UI loads the index from the built site, so search breaks in production until you index it yourself. Install `pagefind` as a devDependency and index after each build: `"build": "astro build && pagefind --site dist"`.
-- **Hosted search sync** — a hosted provider's index is no longer pushed on build; re-upload your search records after each build with the provider's API or CLI.
-- **sitemap.xml** — recreate it with the standard [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) integration.
-- **robots.txt** — ship your own as `public/robots.txt`.
-- **llms.txt / llms-full.txt and agent-readability.json** — write them by hand (or generate them in a build step of your own) and serve them from `public/`.
-- **Platform redirect files** — `_redirects` and `vercel.json` are no longer emitted for static builds. Your redirects still work as Astro-generated meta-refresh pages, or you can move them into your host's own config.
+The ejected app's `build` script runs plain `astro build`, and the artifacts `blume build` layers on top — the search index (and a hosted provider's index sync), `llms.txt` and `llms-full.txt`, `sitemap.xml`, `robots.txt`, `agent-readability.json`, the `.well-known` discovery files, Agent Skills, and the platform `_redirects`/`_headers` files — are still produced: the Blume integration in the ejected `astro.config.mjs` writes them from Astro's `astro:build:done` hook, scanning the project (your `blume.config.ts` and content) the way the CLI did. What the ejected build does not do is the CLI's adapter post-processing: the Vercel and Cloudflare `Accept: text/markdown` routing splices, the Vercel function-bundle audit, and the `--analyze`/`--budget-*` gate.

package/docs/content/syntax.mdx

@@ -384,7 +384,7 @@ flowchart LR
 ```
 ````
 
-Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
+Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one. Diagrams use Mermaid's dagre layout and classic look by default; opt a single diagram into another layout or look through Mermaid front matter (a `config:` block with `layout: elk` or `look: neo`), and the ELK engine loads only for diagrams that ask for it. The rest of this section is a gallery of common types — see the [Mermaid docs](https://mermaid.js.org/intro/) for the full list.
 
 ### Flowchart
 

package/docs/reference/cli.mdx

@@ -111,7 +111,7 @@ Add a `tsconfig.json` extending Astro's config to your project root so authored
 ```json title="tsconfig.json"
 {
   "extends": "astro/tsconfigs/strict",
-  "include": [".blume/.astro/types.d.ts", ".blume/src/env.d.ts", "**/*"]
+  "include": [".blume/.astro/types.d.ts", "**/*"]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -59,6 +59,7 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
+    "bench": "bun bench/run.ts",
     "bundle-docs": "node scripts/bundle-docs.mjs",
     "prepack": "bun run scripts/build.ts && node scripts/bundle-docs.mjs",
     "test": "bun test",
@@ -74,12 +75,12 @@
     "@astrojs/vercel": "^11.0.10",
     "@asyncapi/converter": "^2.0.2",
     "@clack/prompts": "^1.8.0",
-    "@iconify-json/lucide": "^1.2.130",
+    "@iconify-json/lucide": "^1.2.131",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
-    "@pierre/diffs": "^1.4.1",
+    "@pierre/diffs": "^1.4.2",
     "@scalar/astro": "^0.4.18",
     "@scalar/openapi-parser": "^0.29.1",
     "@scalar/openapi-types": "^0.9.5",
@@ -89,7 +90,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^7.0.94",
+    "ai": "^7.0.99",
     "astro": "^7.3.2",
     "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
@@ -99,12 +100,12 @@
     "dompurify": "^3.4.15",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
+    "es-module-lexer": "^3.0.2",
     "fast-xml-parser": "^5.11.1",
     "github-slugger": "^2.0.0",
     "graphql": "^17.0.2",
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
-    "image-size": "^2.0.2",
     "jiti": "^2.7.0",
     "js-yaml": "^5.4.1",
     "katex": "^0.18.7",
@@ -114,7 +115,7 @@
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
-    "mermaid": "^11.17.2",
+    "mermaid": "^12.0.0",
     "micromark-extension-gfm": "^3.0.0",
     "nanotar": "^0.3.0",
     "node-html-parser": "^9.0.4",
@@ -127,8 +128,8 @@
     "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
     "picomatch": "^4.0.7",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "robots-parser": "^3.0.1",
     "satteri": "^0.10.5",
     "semver": "^7.8.5",
@@ -145,10 +146,10 @@
     "ufo": "^1.6.4",
     "undici": "^8.10.2",
     "write-file-atomic": "^8.0.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.2"
   },
   "devDependencies": {
-    "@ai-sdk/openai-compatible": "^3.0.45",
+    "@ai-sdk/openai-compatible": "^3.0.48",
     "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
@@ -156,16 +157,17 @@
     "@sanity/client": "^8.6.1",
     "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
-    "@types/node": "^22.20.1",
+    "@types/node": "^22.20.2",
     "@types/picomatch": "^4.0.3",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@types/semver": "^7.8.0",
     "@types/write-file-atomic": "^4.0.3",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "algoliasearch": "^5.57.0",
+    "algoliasearch": "^5.59.0",
     "bun-types": "^1.4.2",
     "flexsearch": "^0.8.212",
+    "mitata": "1.0.34",
     "typesense": "^3.0.6"
   },
   "peerDependencies": {

package/src/ai/api/handlers.ts

@@ -11,10 +11,11 @@ import {
 } from "../mcp/query.ts";
 import type { SearchHitPayload } from "../mcp/query.ts";
 import {
-  API_BASE,
   API_PAGES_PATH,
   API_SEARCH_PATH,
   OPENAPI_PATH,
+  pageJsonPath,
+  pageParam,
 } from "./paths.ts";
 import { problemResponse } from "./problem.ts";
 
@@ -85,10 +86,6 @@ export const jsonResponse = (payload: ApiPayload, status = 200): Response =>
     status,
   });
 
-/** The `pages/{route}.json` path segment for a route (`index` for home). */
-export const pageParam = (route: string): string =>
-  route === "/" ? "index" : route.slice(1);
-
 /** The absolute (or root-relative) URL for a base-less path. */
 const siteUrl = (path: string, context: ApiSiteContext): string => {
   const based = withBasePath(context.base, path);
@@ -98,7 +95,7 @@ const siteUrl = (path: string, context: ApiSiteContext): string => {
 const summarize = (route: McpRoute, data: McpData): ApiPageSummary => {
   const summary: ApiPageSummary = {
     contentType: route.contentType,
-    json: siteUrl(`${API_BASE}/pages/${pageParam(route.route)}.json`, data),
+    json: siteUrl(pageJsonPath(route.route), data),
     lastModified: route.lastModified,
     locale: route.locale,
     markdownUrl: siteUrl(`/${pageParam(route.route)}.md`, data),
@@ -163,7 +160,7 @@ export const pageResponse = (data: McpData, route: string): Response => {
     return problemResponse({
       code: "PAGE_NOT_FOUND",
       detail: `No documentation page has the route "${route}".`,
-      instance: siteUrl(`${API_BASE}/pages/${pageParam(route)}.json`, data),
+      instance: siteUrl(pageJsonPath(route), data),
       resolution: `List every page at ${siteUrl(API_PAGES_PATH, data)}, or discover the API through ${siteUrl(OPENAPI_PATH, data)}.`,
       status: 404,
       title: "Page not found",

package/src/ai/api/paths.ts

@@ -12,3 +12,11 @@ export const API_PAGES_PATH = `${API_BASE}/pages.json`;
 export const API_PAGE_PATH = `${API_BASE}/pages/{route}.json`;
 export const API_NAVIGATION_PATH = `${API_BASE}/navigation.json`;
 export const API_SEARCH_PATH = `${API_BASE}/search`;
+
+/** The `pages/{route}.json` path segment for a route (`index` for home). */
+export const pageParam = (route: string): string =>
+  route === "/" ? "index" : route.slice(1);
+
+/** The base-less served path of a route's per-page JSON document. */
+export const pageJsonPath = (route: string): string =>
+  `${API_BASE}/pages/${pageParam(route)}.json`;

package/src/ai/api/spec.ts

@@ -1,3 +1,4 @@
+import { apiNamePhrase } from "../../core/api-name.ts";
 import { withBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import {
@@ -658,7 +659,7 @@ export const buildApiSpec = (input: ApiSpecInput): ApiSpecDocument => {
       `Read-only JSON API over the ${input.name} documentation${input.description ? `: ${input.description}` : "."}`,
       "Every operation is public and needs no authentication. Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`, a `detail`, and a `resolution` hint.",
     ].join("\n\n"),
-    title: `${input.name} API`,
+    title: apiNamePhrase(input.name),
     version: input.version,
     "x-generator": `blume@${input.version}`,
   };