blume 1.4.2 → 1.4.3

package/dist/types/core/base-path.d.ts

@@ -22,6 +22,14 @@ export declare const normalizeBasePath: (input?: string) => string;
  * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
  */
 export declare const normalizePath: (path: string) => string;
+/**
+ * Canonicalize a route-ish string (a configured route, a page path, an agent-
+ * supplied route) to `/` or `/seg[/seg…]`: trimmed, exactly one leading slash,
+ * no trailing slash. The shared spelling of what openapi/references,
+ * ai/ask-context, and ai/mcp/server each hand-rolled with slightly different
+ * regexes.
+ */
+export declare const normalizeRoute: (input: string) => string;
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

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

@@ -171,6 +171,8 @@ export interface SanitySource {
 /** A Notion database; pages become entries, blocks become MDX. */
 export interface NotionSource {
     type: "notion";
+    /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+    concurrency?: number;
     /** Notion database id. */
     database: string;
     /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
@@ -565,6 +567,12 @@ export interface AskConfig {
      * limiting, and streaming. Accepts an absolute URL or root-relative path.
      */
     endpoint?: string;
+    /**
+     * Extra system-prompt text appended to the built-in instructions — use it
+     * for identity, language, or tone. The built-in grounding behavior (answer
+     * from the retrieved excerpts, cite pages as Markdown links) is preserved.
+     */
+    instructions?: string;
     /** Model id to use. Defaults to `openai/gpt-5.5`. */
     model?: string;
     /** Which backend routes the request. Defaults to `gateway`. */

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

@@ -189,6 +189,7 @@ declare const contentSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     query: z.ZodString;
     type: z.ZodLiteral<"sanity">;
 }, z.core.$strip>, z.ZodObject<{
+    concurrency: z.ZodOptional<z.ZodNumber>;
     database: z.ZodString;
     pollInterval: z.ZodOptional<z.ZodNumber>;
     prefix: z.ZodOptional<z.ZodString>;
@@ -244,6 +245,7 @@ declare const aiConfigSchema: z.ZodObject<{
         baseUrl: z.ZodOptional<z.ZodURL>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         endpoint: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
         model: z.ZodDefault<z.ZodString>;
         provider: z.ZodDefault<z.ZodEnum<{
             gateway: "gateway";
@@ -400,6 +402,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             baseUrl: z.ZodOptional<z.ZodURL>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             endpoint: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodString>;
             model: z.ZodDefault<z.ZodString>;
             provider: z.ZodDefault<z.ZodEnum<{
                 gateway: "gateway";
@@ -527,6 +530,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             query: z.ZodString;
             type: z.ZodLiteral<"sanity">;
         }, z.core.$strip>, z.ZodObject<{
+            concurrency: z.ZodOptional<z.ZodNumber>;
             database: z.ZodString;
             pollInterval: z.ZodOptional<z.ZodNumber>;
             prefix: z.ZodOptional<z.ZodString>;

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

@@ -1,4 +1,4 @@
-import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
+import type { FolderMeta, FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 /**
  * A single content item, normalized by a source adapter. Adapters lower their
@@ -41,6 +41,14 @@ export interface SourceLoadResult {
     entries: SourceEntry[];
     /** Source-level diagnostics (e.g. an offline cache fallback warning). */
     diagnostics: Diagnostic[];
+    /**
+     * Folder meta the source derives for the sidebar groups its entries create,
+     * keyed by locale-stripped group path (the `meta.ts` key space). The OpenAPI
+     * source labels each tag directory with the spec's own tag name, so the
+     * sidebar shows `OAuth2`/`Größe` instead of a re-humanized slug. Merged
+     * beneath user-authored meta files, which always win.
+     */
+    folderMeta?: Record<string, FolderMeta>;
 }
 /**
  * Per-source runtime context, handed to an adapter factory at construction so

package/dist/types/openapi/references.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+export { normalizeRoute } from "../core/base-path.ts";
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
  * labels, and a renderer choice — no file IO, so the content source, the
@@ -54,9 +55,14 @@ export interface ReferenceSource {
      */
     collisions?: string[];
 }
+/**
+ * Lowercase, hyphen-separated slug: `Add a Pet!` -> `add-a-pet`. Unicode
+ * letters are kept (`Größe` -> `größe`), NFC-normalized so canonically
+ * equivalent spellings (NFD input from macOS tooling) land on one slug.
+ * Non-ASCII slugs rely on the emitter percent-encoding the URL where a raw
+ * URI is required (sitemap, canonical).
+ */
 export declare const slugify: (text: string) => string;
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-export declare const normalizeRoute: (route: string) => string;
 /**
  * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
  * by default); AsyncAPI is always rendered by Scalar for now.

package/docs/configuration/ai.mdx

@@ -136,6 +136,22 @@ ai: {
 
 `label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.
 
+### Custom instructions
+
+Add your own system-prompt text with `instructions` — identity, language, tone, or anything else the assistant should keep in mind:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    instructions:
+      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
+  },
+}
+```
+
+Your text is **appended to** the built-in instructions rather than replacing them: the built-in part carries the [grounding](#grounding) contract — answer only from the retrieved pages, cite them as Markdown links — that the chat panel's citations depend on, so it stays intact whatever you add.
+
 ### Grounding
 
 Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
@@ -185,15 +201,17 @@ A static build with Ask AI enabled and no external `endpoint` fails fast with a
 
 By default Ask AI routes through the **Vercel AI Gateway**: `model` is a `provider/model` string, so you switch models by changing it (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up automatically when you deploy on Vercel.
 
-Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable, and the matching provider SDK is added to your project's runtime automatically when you build — only the one you use:
+Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable and streams through a provider SDK you install in your project — only the one you use:
+
+| `provider` | `model` | API key env var | SDK to install |
+| --- | --- | --- | --- |
+| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` | none — ships with Blume |
+| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
+| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
+| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
+| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` | `@ai-sdk/openai-compatible` |
 
-| `provider` | `model` | API key env var |
-| --- | --- | --- |
-| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` |
-| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` |
-| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` |
-| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` |
-| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` |
+The SDKs are optional peer dependencies, so add the one your backend needs to your project (e.g. `npm install @openrouter/ai-sdk-provider`). If it's missing, the build warns with the exact package name before Vite would fail to resolve the import.
 
 For example, to use OpenRouter:
 

package/docs/content/sources.mdx

@@ -146,7 +146,7 @@ export default defineConfig({
 });
 ```
 
-The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build.
+The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build. API calls are paced through a small request pool (3 at a time, matching Notion's per-integration rate limit) so databases with hundreds of pages import without tripping `429` responses; set `concurrency` on the source to tune it.
 
 ## Preview and sync
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -86,6 +86,7 @@
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4",
+    "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
     "ai": "^7.0.42",
     "astro": "^7.1.0",
@@ -93,6 +94,7 @@
     "chokidar": "^5.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
+    "cross-spawn": "^7.0.6",
     "dompurify": "^3.4.13",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
@@ -113,10 +115,16 @@
     "medium-zoom": "^1.1.0",
     "mermaid": "^11.16.1",
     "micromark-extension-gfm": "^3.0.0",
+    "nanotar": "^0.3.0",
     "node-html-parser": "^9.0.0",
     "openapi-sampler": "^1.7.4",
+    "p-limit": "^7.3.1",
+    "p-map": "^7.0.6",
+    "p-retry": "^8.0.0",
+    "package-manager-detector": "^1.8.0",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",
+    "perfect-debounce": "^2.1.0",
     "picomatch": "^4.0.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -131,11 +139,13 @@
     "tinyglobby": "^0.2.10",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
+    "ufo": "^1.6.4",
     "undici": "^8.9.0",
     "write-file-atomic": "^8.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.0",

package/src/ai/agent-readability.ts

@@ -1,6 +1,7 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
 
@@ -42,7 +43,7 @@ const askApiUrl = (
     return abs("/api/ask");
   }
   return site && endpoint.startsWith("/")
-    ? `${site.replace(/\/+$/u, "")}${endpoint}`
+    ? absoluteUrl(site, endpoint)
     : endpoint;
 };
 
@@ -88,7 +89,7 @@ export const buildAgentReadability = (
   const deployBase = normalizeBasePath(config.deployment.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
-    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+    return site ? absoluteUrl(site, based) : based;
   };
 
   // Advertise `Accept: text/markdown` negotiation only where the deployed site

package/src/ai/api-catalog.ts

@@ -1,6 +1,6 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import { trimEnd } from "../core/trim.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { resolveReferences } from "../openapi/references.ts";
 
 /**
@@ -32,7 +32,7 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
   const deployBase = normalizeBasePath(config.deployment.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
-    return site ? `${trimEnd(site, "/")}${based}` : based;
+    return site ? absoluteUrl(site, based) : based;
   };
 
   const entries: LinksetEntry[] = [];

package/src/ai/ask-context.ts

@@ -1,3 +1,4 @@
+import { normalizeRoute } from "../core/base-path.ts";
 import { buildOramaIndex, queryOramaIndex } from "../search/orama-index.ts";
 import type { OramaDoc } from "../search/orama-index.ts";
 
@@ -90,11 +91,39 @@ const STOPWORDS = new Set([
   "your",
 ]);
 
+/** A run of letters, combining marks and digits inside a word-like segment. */
+const TERM = /[\p{L}\p{M}\p{N}]+/gu;
+
+/**
+ * Word-shaped pieces of a query, NFC-normalized and lowercased. Languages
+ * written without spaces (the CJK/Thai sites the Orama tokenizer goes out of
+ * its way to support) have no delimiter for a regex to split on, so the query
+ * is cut with `Intl.Segmenter` where available — otherwise every excerpt
+ * window silently degrades to the head of the page. The regex fallback covers
+ * runtimes without the segmenter and still handles spaced scripts correctly.
+ */
+const segmentQuery = (query: string): string[] => {
+  const lowered = query.normalize("NFC").toLowerCase();
+  if (typeof Intl.Segmenter !== "function") {
+    return lowered.match(TERM) ?? [];
+  }
+  const pieces: string[] = [];
+  const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  for (const segment of segmenter.segment(lowered)) {
+    if (segment.isWordLike) {
+      pieces.push(segment.segment);
+    }
+  }
+  return pieces;
+};
+
 /** Distinct, meaningful lowercase terms from a query (drops stopwords). */
-const queryTerms = (query: string): string[] =>
-  [...new Set(query.toLowerCase().match(/[a-z0-9]+/gu))].filter(
+const queryTerms = (query: string): string[] => {
+  const terms = segmentQuery(query).flatMap((piece) => piece.match(TERM) ?? []);
+  return [...new Set(terms)].filter(
     (term) => term.length >= 2 && !STOPWORDS.has(term)
   );
+};
 
 /**
  * The grounding preamble. The model is told to answer strictly from the injected
@@ -104,13 +133,6 @@ const queryTerms = (query: string): string[] =>
 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).";
 
-/** Normalize a page path to a document `route` (`/`, `/a/b`, no trailing slash). */
-const normalizeRoute = (input: string): string => {
-  const noTrailing = input.trim().replace(/\/+$/u, "");
-  const withSlash = noTrailing.startsWith("/") ? noTrailing : `/${noTrailing}`;
-  return withSlash === "" ? "/" : withSlash;
-};
-
 /** The most recent non-empty user message, used as the retrieval query. */
 const lastUserMessage = (messages: AskMessage[]): string => {
   for (let i = messages.length - 1; i >= 0; i -= 1) {
@@ -137,7 +159,9 @@ export const relevantExcerpt = (
   query: string,
   max: number
 ): string => {
-  const trimmed = content.trim();
+  // NFC to match the normalized query terms; positions are computed on (and
+  // sliced from) this same string, so offsets stay aligned.
+  const trimmed = content.normalize("NFC").trim();
   if (trimmed.length <= max) {
     return trimmed;
   }
@@ -199,9 +223,15 @@ export const relevantExcerpt = (
  * grounded system prompt — the retrieved excerpts plus the page the user is
  * viewing — or `undefined` when there is nothing to ground on, so the endpoint
  * can fall back to its plain prompt.
+ *
+ * `options.instructions` (the `ai.ask.instructions` config) is appended after
+ * 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.
  */
 export const createAskContext = (
-  data: AskData
+  data: AskData,
+  options?: { instructions?: string }
 ): ((
   messages: AskMessage[],
   page?: AskPage
@@ -213,6 +243,9 @@ export const createAskContext = (
     return dbPromise;
   };
   const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
+  const instruction = options?.instructions
+    ? `${BASE_INSTRUCTION}\n\n${options.instructions}`
+    : BASE_INSTRUCTION;
 
   return async (messages, page) => {
     const list = Array.isArray(messages) ? messages : [];
@@ -257,6 +290,6 @@ export const createAskContext = (
     if (sections.length === 0) {
       return;
     }
-    return `${BASE_INSTRUCTION}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
+    return `${instruction}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
   };
 };

package/src/ai/llms.ts

@@ -2,6 +2,7 @@ import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { absoluteUrl } from "../core/site-url.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
@@ -17,7 +18,7 @@ import { applyAgentVisibility } from "./visibility.ts";
 // spaces or non-ASCII must still yield a valid Markdown link.
 const pageUrl = (route: string, site?: string, base = ""): string => {
   const path = withBasePath(base, route);
-  return encodeURI(site ? `${site.replace(/\/$/u, "")}${path}` : path);
+  return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
 // Drafts, hidden, and ordinary `noindex` pages are excluded. Generated API

package/src/ai/mcp/discovery.ts

@@ -1,6 +1,6 @@
 import { withBasePath } from "../../core/base-path.ts";
-import { trimEnd } from "../../core/trim.ts";
-import { slugify } from "../../openapi/references.ts";
+import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
+import { trimChar } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
@@ -20,7 +20,7 @@ const serverUrl = (input: McpDiscoveryInput): string => {
   const path = withBasePath(input.base, input.route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  return input.site ? `${trimEnd(input.site, "/")}${path}` : path;
+  return input.site ? absoluteUrl(input.site, path) : path;
 };
 
 /**
@@ -49,10 +49,29 @@ const CARD_TEXT_MAX = 100;
 const truncate = (text: string): string =>
   text.length > CARD_TEXT_MAX ? `${text.slice(0, CARD_TEXT_MAX - 1)}…` : text;
 
+// The server-card schema constrains `name` to `namespace/server` in ASCII
+// (`^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$`), so the display name cannot reuse the
+// route slugifier, which keeps Unicode letters. Decompose (NFKD) and drop
+// combining marks first so an accented name transliterates (`Café` → `cafe`)
+// instead of losing the letter.
+const NON_ASCII_SLUG = /[^a-z0-9]+/gu;
+const COMBINING_MARKS = /\p{M}+/gu;
+
+const asciiSlugify = (text: string): string =>
+  trimChar(
+    text
+      .normalize("NFKD")
+      .replace(COMBINING_MARKS, "")
+      .toLowerCase()
+      .replace(NON_ASCII_SLUG, "-"),
+    "-"
+  );
+
 /**
  * The card's identity in the schema's reverse-DNS `namespace/server` form:
  * the site hostname reversed (`useblume.dev` → `dev.useblume`), or
- * `localhost` when no site is configured, plus the slugged display name.
+ * `localhost` when no site is configured, plus the slugged display name (an
+ * entirely non-ASCII name falls back to `docs`).
  */
 const reverseDnsName = (input: McpDiscoveryInput): string => {
   let namespace = "localhost";
@@ -66,7 +85,7 @@ const reverseDnsName = (input: McpDiscoveryInput): string => {
       // Not a parsable URL; the local namespace is honest enough.
     }
   }
-  return `${namespace}/${slugify(input.name) || "docs"}`;
+  return `${namespace}/${asciiSlugify(input.name) || "docs"}`;
 };
 
 const HTTP_URL = /^https?:\/\//u;
@@ -109,6 +128,6 @@ export const buildMcpServerCard = (
     transports: [{ endpoint: url, type: "streamable-http" }],
     url,
     version: input.version,
-    ...(input.site ? { websiteUrl: trimEnd(input.site, "/") } : {}),
+    ...(input.site ? { websiteUrl: siteRoot(input.site) } : {}),
   };
 };