blume 1.6.5 → 1.7.0

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/components/layout/nav-utils.d.ts

@@ -1,4 +1,4 @@
-import type { NavNode, NavTab } from "../../core/types.ts";
+import type { NavNode, NavTab, Navigation } from "../../core/types.ts";
 /** A flat, ordered page reference used for previous/next pagination. */
 export interface FlatPage {
     route: string;
@@ -58,3 +58,35 @@ export declare const getPagination: (flat: FlatPage[], route: string) => {
     next: FlatPage | null;
     prev: FlatPage | null;
 };
+/**
+ * A stable id for every group in a sidebar — `g<n>` by pre-order position in
+ * the full tree. The layout hands `NavTree` a scoped view of that tree (a
+ * tab's section, or the sidebar minus the tab sections), so positions within
+ * the rendered slice differ from page to page; these ids name the same group
+ * everywhere, which the drill-in panels and the deferred-section fragments
+ * (`/blume-nav/…`) rely on. Keyed by node identity: the scoped views reuse
+ * the full tree's node objects.
+ */
+export declare const navGroupIds: (sidebar: NavNode[]) => Map<NavNode, string>;
+/** Whether any group in a sidebar renders as a disclosure or a drill-in panel. */
+export declare const hasDeferrableGroups: (sidebar: NavNode[]) => boolean;
+/** One of the navigation trees a site renders, by URL segment. */
+export interface NavVariant {
+    /** `current`, or an archived version id. */
+    version: string;
+    /** `default`, or a locale code. */
+    locale: string;
+    navigation: Navigation;
+}
+/**
+ * Every navigation tree the runtime data holds — the default, each locale's,
+ * and each archived version's per locale — keyed the way the deferred
+ * sidebar fragments' URLs are (`/blume-nav/<version>/<locale>/…`). An
+ * unlocalized version tree is keyed by `""` in the data; it maps to
+ * `default` here.
+ */
+export declare const navVariants: (data: {
+    navigation: Navigation;
+    navigationByLocale: Record<string, Navigation>;
+    navigationByVersion: Record<string, Record<string, Navigation>>;
+}) => NavVariant[];

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/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<{

package/dist/types/theme/fonts.d.ts

@@ -71,27 +71,27 @@ export declare const GOOGLE_FONTS: {
     "dm-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     figtree: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "fira-code": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     geist: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "geist-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "ibm-plex-mono": {
         category: "mono";
@@ -101,7 +101,7 @@ export declare const GOOGLE_FONTS: {
     "ibm-plex-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "ibm-plex-serif": {
         category: "serif";
@@ -111,77 +111,77 @@ export declare const GOOGLE_FONTS: {
     inter: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "inter-tight": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "jetbrains-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     lora: {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     manrope: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     merriweather: {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "open-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "playfair-display": {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "plus-jakarta-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     roboto: {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "roboto-mono": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-code-pro": {
         category: "mono";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-sans-3": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "source-serif-4": {
         category: "serif";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "space-grotesk": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
     "space-mono": {
         category: "mono";
@@ -191,7 +191,7 @@ export declare const GOOGLE_FONTS: {
     "work-sans": {
         category: "sans";
         family: string;
-        weights: number[];
+        weights: string[];
     };
 };
 export type FontSlug = keyof typeof GOOGLE_FONTS;

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.
@@ -141,6 +141,27 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 
 Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.
 
+## Build cache
+
+Blume keeps two caches a build can reuse. Astro's and Vite's caches live under `.blume/.cache/` (the content store and image transforms among them). Rendered [OG cards](/docs/discoverability/open-graph#card-cache) live in `node_modules/.cache/blume/og`, so a rebuild renders only the cards whose title, description, or branding changed. Whether a platform keeps that directory between deploys varies:
+
+- **Vercel** restores `node_modules/**` from its build cache, so cards carry over (the cache is 1 GB, retained for a month, and keyed per branch — a new branch starts from the production cache).
+- **Netlify** restores `node_modules`, so cards carry over.
+- **Cloudflare Workers Builds** persists only package-manager caches and, for a detected Astro project, `node_modules/.astro` — never `node_modules/.cache` — so every deploy renders every card there.
+- **GitHub Actions** and other runners you manage keep nothing unless you cache the directory yourself:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: node_modules/.cache/blume/og
+    key: blume-og-${{ runner.os }}-${{ hashFiles('**/bun.lock', '**/package-lock.json', '**/pnpm-lock.yaml') }}
+    restore-keys: blume-og-${{ runner.os }}-
+```
+
+Cards are keyed by content, so an imprecise key is fine: a restored cache only ever saves renders, never serves a wrong card.
+
+One install command discards the cache on every platform: `npm ci` deletes `node_modules` before installing. Keep `npm install`, `bun install`, or `pnpm install` as the install command to get the reuse.
+
 ## Build summary
 
 Every build prints a summary — output mode, adapter, resolved site URL, search provider, redirect count, sitemap and `llms.txt` status, and any enabled server features — so you can confirm what shipped (including anything auto-detected) before you deploy.

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/navigation.mdx

@@ -69,6 +69,8 @@ navigation: {
 `page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
 :::
 
+In both `group` and `page` mode, a section that isn't open on the current page is left out of that page's HTML and fetched the first time it's opened (it's prefetched as soon as the pointer or focus reaches its row, so the open is usually instant, and a section fetched once is kept for the rest of the visit). On a large site this is most of a page's weight: only the open section's rows ship with the page. The rows are prerendered fragments under `/blume-nav/`, so they need no server. Readers without JavaScript see the open section and the group rows; the sitemap, the previous/next links, and the open section keep every page reachable for crawlers.
+
 ### Per-group overrides
 
 Any generated group can opt out of the global mode — no explicit sidebar required. Set `display` in the folder's [`meta.ts`](/docs/content/meta), or — when the folder has an `index` page — under `sidebar` in that page's frontmatter, and only that group changes:

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. 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.
+Diagrams render on the client, so this is an MDX-only feature, and the Mermaid library loads only on pages that include one; a site with no diagram doesn't ship it at all. 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/discoverability/open-graph.mdx

@@ -94,6 +94,10 @@ Google families are fetched at build — so a build that uses them needs network
 
 An explicit `og.fonts: []` opts out entirely: cards keep the built-in font even when `theme.fonts` is set.
 
+## Card cache
+
+Rendered cards are cached on disk between builds, keyed by everything that decides their pixels: the page title and description, the brand text, logo, palette, footer text, and fonts (a local font file by its contents), plus the Blume version. A rebuild renders only the cards whose inputs changed and reads the rest back; the build log reports how many were reused. The cache lives in `node_modules/.cache/blume/og`; on a platform that keeps `node_modules` between builds (Vercel and Netlify do, Cloudflare does not) or a CI runner that caches that directory (see [Build cache](/docs/deployment#build-cache)), a deploy that touches a handful of pages re-renders a handful of cards. Cards that no page asked for are removed after each build, so the directory only ever holds the current site's cards.
+
 ## Custom page titles
 
 A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):

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.5",
+  "version": "1.7.0",
   "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",
@@ -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",
@@ -166,6 +167,7 @@
     "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}`,
   };