blume 2.0.3 → 2.1.1

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -156,22 +156,31 @@ const ICONS = {
 
 // --- Frontmatter field policy ----------------------------------------------
 // Top-level keys Blume's strict schema rejects: delete the whole block, report.
-const DROP = new Set([
-  "groups",
-  "hideApiMarker",
-  "hideFooterPagination",
-  "iconType",
-  "keywords",
-  "mode",
-  "public",
-  "rss",
-]);
+const DROP = new Set(["groups", "hideApiMarker", "iconType", "public", "rss"]);
 
-// Mintlify-only keys → Blume nested target. `[parent, child]`.
+// Keys whose fate depends on their value: the source value (and its line) →
+// the line that replaces it, the line itself to keep it, or `null` to drop it
+// (a value Blume has no counterpart for, or one that restates its default).
+const REPLACE = {
+  hideFooterPagination: (value) =>
+    value === "true" ? "pagination: false" : null,
+  mode: (value, line) => (value === "assistant" ? null : line),
+};
+
+// Mintlify-only keys → Blume nested target. `[parent, child]`, plus a value
+// mapper where the meaning flips: it returns the new value, or `null` to drop a
+// value that restates Blume's default.
 const RENAME = {
+  boost: ["search", "boost"],
   canonical: ["seo", "canonical"],
+  keywords: ["search", "keywords"],
   "og:image": ["seo", "image"],
   ogImage: ["seo", "image"],
+  searchable: [
+    "search",
+    "exclude",
+    (value) => (value === "false" ? "true" : null),
+  ],
   sidebarTitle: ["sidebar", "label"],
   tag: ["sidebar", "badge"],
 };
@@ -179,7 +188,8 @@ const RENAME = {
 // Keys we deliberately do NOT auto-transform — they usually mean the page is an
 // OpenAPI endpoint stub that should be deleted (Blume generates operation pages),
 // or else a normal page that just loses the key. Flag for the human; never guess.
-const FLAG = new Set(["api", "asyncapi", "openapi"]);
+// (`api` is not one: a hand-written endpoint page keeps it as written.)
+const FLAG = new Set(["asyncapi", "openapi"]);
 
 // Which change kinds actually edit the file. Report-only kinds (flags,
 // unknowns, conflicts, manual-rename notices) leave the bytes untouched.
@@ -334,11 +344,41 @@ const rewriteFields = (fm) => {
       changes.push({ detail: tk.key, kind: "flag" });
       continue;
     }
+    if (Object.hasOwn(REPLACE, tk.key)) {
+      const [start, end] = blockRange(fm, i);
+      const value = tk.value.replace(
+        /^(?<q>["'])(?<inner>.*)\k<q>$/u,
+        "$<inner>"
+      );
+      const line =
+        end - start === 1 ? REPLACE[tk.key](value, fm[start]) : undefined;
+      if (line === undefined) {
+        changes.push({ detail: tk.key, kind: "rename-manual" });
+      } else if (line === null) {
+        fm.splice(start, 1);
+        changes.push({ detail: `${tk.key}: ${value}`, kind: "drop" });
+      } else if (line !== fm[start]) {
+        const [key] = line.split(":");
+        if (fm.some((other, j) => j !== start && topKey(other)?.key === key)) {
+          changes.push({
+            detail: `${tk.key} → ${key} (child-exists)`,
+            kind: "rename-conflict",
+          });
+        } else {
+          fm[start] = line;
+          changes.push({
+            detail: `${tk.key}: ${value} → ${line}`,
+            kind: "rename",
+          });
+        }
+      }
+      continue;
+    }
     const target = RENAME[tk.key];
     if (!target) {
       continue;
     }
-    const [parent, child] = target;
+    const [parent, child, map] = target;
     const [start, end] = blockRange(fm, i);
     if (end - start !== 1 || tk.value === "") {
       // Multi-line or valueless source — too structured to move safely.
@@ -348,12 +388,18 @@ const rewriteFields = (fm) => {
       });
       continue;
     }
+    const value = map ? map(tk.value) : tk.value;
+    if (value === null) {
+      fm.splice(start, 1);
+      changes.push({ detail: `${tk.key}: ${tk.value}`, kind: "drop" });
+      continue;
+    }
     // Remove the source line before inserting: setNested splices into the
     // parent block, and when that block sits above the source key the insert
     // would otherwise shift `start` onto the wrong line. Failure paths don't
     // mutate `fm`, so the line can be restored as-is on conflict.
     const [removed] = fm.splice(start, 1);
-    const placed = setNested(fm, parent, child, tk.value);
+    const placed = setNested(fm, parent, child, value);
     if (placed.ok) {
       if (placed.index < start) {
         // The insert above the cursor pushed the unvisited lines down one

package/skills/blume-write-skill/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: blume-write-skill
+description: Write the agent skill for a product's Blume docs site — one SKILL.md, grounded in the docs, that teaches a coding agent to use the product (setup, core concepts, common tasks, gotchas) and links each topic's page. Blume publishes it at the site's /skill.md in place of the page map it generates. Use when asked to write, improve, or refresh a docs site's agent skill, or when `blume skill` hands you this task.
+---
+
+# Write a docs site's agent skill
+
+Every Blume site already publishes a generated skill at `/skill.md`: a map of its pages with their one-line descriptions, built without a model. It tells an agent where things are, not how the product works. Your job is to write the skill that does: what the product is, how to set it up, the concepts and tasks that matter, and where it bites, with every topic linked to the page that covers it.
+
+The reader is a coding agent working in someone else's project. It loaded your skill because a task touches this product, and it needs to act correctly without reading the whole site first.
+
+## Ground rules
+
+- **Only what the docs say.** Every claim, command, config key, flag, environment variable, and code sample must come from a page in the content root, copied rather than paraphrased. Never fill a gap from memory or from what similar products do. Where the docs don't answer something the skill needs, leave it out and list it in your report as a docs gap.
+- **One file.** Keep it a lone `SKILL.md`: no `references/`, `scripts/`, or `assets/`. A single file is what the site serves at `/skill.md` and what an agent can fetch in one request. Depth lives in the docs, so link to them instead of copying them in.
+- **Absolute links to Markdown.** Link pages as `<site><route>.md` (the home page is `<site>/index.md`), using the site URL your prompt gives. Link only pages that exist: a page's route is its path under the content root without the extension, and a folder's `index` page takes the folder's route.
+- **Keep the given name.** The frontmatter `name` must be exactly the one in your prompt. That match is what makes your skill replace the generated one.
+- **Short beats complete.** Aim for well under 300 lines. Skip anything a capable agent already knows (general programming, Markdown, how HTTP works) and anything it can look up from a link when it needs it.
+
+## Workflow
+
+1. **Read the docs.** Start with `blume.config.ts` (the site's title, description, `content.root`, navigation, API references) and the `meta.ts` files, which give the sidebar order. Then read the home page, the quickstart or installation page, each core-concept page, the configuration reference, the API reference overview, and any troubleshooting or FAQ pages. If the site has been built, its `llms.txt` lists every page with its description.
+
+2. **Decide what matters.** Before writing, note:
+   - the product in two or three sentences: what it is, who uses it, and how it's installed or reached
+   - the five to ten tasks people most often come to the docs to do
+   - the concepts an agent must understand to do those tasks right
+   - the sharp edges: limits, required setup, defaults that surprise people, common errors, and anything deprecated along with what replaced it
+
+3. **Write the skill.** Use this shape, dropping any section the docs give you nothing for:
+
+   ```markdown
+   ---
+   name: <the name from your prompt>
+   description: <What the product is and when to use this skill, in the words a user would type: the product name, its package and CLI names, its key concepts. At most 1024 characters.>
+   ---
+
+   # <Product>
+
+   <Two or three sentences: what it is, who it's for, how to install or reach it.>
+
+   ## Setup
+
+   <Install, configure, and authenticate, verbatim from the docs, with a link to the page.>
+
+   ## Core concepts
+
+   - **<Concept>**: <one line>. [<Page title>](<site><route>.md)
+
+   ## Common tasks
+
+   ### <Task>
+
+   1. <Step, with the exact command or code from the docs.>
+
+   See [<Page title>](<site><route>.md).
+
+   ## Gotchas
+
+   - <The limit, default, or error, and what to do about it.>
+
+   ## Where to look
+
+   - [<Section>](<site><route>.md): <when to read it>
+   - [llms.txt](<site>/llms.txt): every page with a one-line summary.
+   ```
+
+   The `description` decides whether an agent loads the skill at all, so spend time on it. Name the product the way users do, and cover the situations it's for ("setting up X", "calling the X API", "configuring X"). Write the body in the imperative, for an agent that will act on it.
+
+   If the site serves an MCP server or other agent surfaces, the generated skill names them. Carry those lines over under "Where to look".
+
+4. **Check it.**
+   - Every link points at a page that exists in the content root, as `<site><route>.md`.
+   - Every command, code sample, config key, and default appears in the docs as written.
+   - The frontmatter parses, `name` is exactly as given, and `description` is 1024 characters or fewer.
+   - Then run the docs build (`blume build`). The build output's `skill.md` should now be yours, and `.well-known/agent-skills/index.json` should list the name once.
+
+5. **Report.** Say where you wrote the skill and any config you changed, summarize what it covers, and list the docs gaps you found: questions the skill needed answered that no page does. Those are worth fixing in the docs.
+
+## Keeping it current
+
+A hand-written skill doesn't update itself the way the generated one does. After a meaningful docs change (new features, renamed APIs, a changed setup flow), run `blume skill` again to refresh it. Update the existing file rather than starting over, and keep what's still true.

package/src/ai/agent-readability.ts

@@ -8,6 +8,7 @@ import { buildRssFeeds } from "../deploy/rss.ts";
 import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, API_SEARCH_PATH, OPENAPI_PATH } from "./api/paths.ts";
+import { servesSkillsIndex } from "./skills.ts";
 
 /** Token map for the machine-readable content-usage echo. */
 const USAGE_TOKENS: [keyof ContentSignalPolicy, string][] = [
@@ -145,7 +146,7 @@ const wellKnownArtifacts = (
   if (hasApiCatalog(config)) {
     artifacts.apiCatalog = abs("/.well-known/api-catalog");
   }
-  if (config.agents.skills) {
+  if (servesSkillsIndex(config)) {
     artifacts.agentSkills = abs("/.well-known/agent-skills/index.json");
   }
   return artifacts;

package/src/ai/agent-surface.ts

@@ -11,7 +11,8 @@ export interface EmittedAgentSurface {
   mcp: boolean;
   /**
    * A skills discovery index is served: generated from `agents.skills` (at
-   * least one valid skill), or shipped by the user in `public/`.
+   * least one valid skill) or the site skill (`agents.skillMd`), or shipped
+   * by the user in `public/`.
    */
   skills: boolean;
 }
@@ -33,12 +34,12 @@ export const servesMcp = (
   );
 
 /**
- * The config the discovery documents are built from: `agents.mcp` and
- * `agents.skills` switched off when the build didn't emit them, so llms.txt,
- * agent-readability.json, the catalogs, and the header rules only point at
- * what is there. A config flag says what was asked for; the MCP server is
- * skipped when a page owns its route, and skills publish nothing when their
- * directory is missing or holds no valid skill.
+ * The config the discovery documents are built from: `agents.mcp`,
+ * `agents.skills`, and `agents.skillMd` switched off when the build didn't
+ * emit them, so llms.txt, agent-readability.json, the catalogs, and the
+ * header rules only point at what is there. A config flag says what was asked
+ * for; the MCP server is skipped when a page owns its route, and skills
+ * publish nothing when their directory is missing or holds no valid skill.
  */
 export const advertisedConfig = (
   config: ResolvedConfig,
@@ -51,6 +52,7 @@ export const advertisedConfig = (
       ...config.agents.mcp,
       enabled: config.agents.mcp.enabled && emitted.mcp,
     },
+    skillMd: config.agents.skillMd && emitted.skills,
     skills: emitted.skills ? config.agents.skills : undefined,
   },
 });

package/src/ai/ai-catalog.ts

@@ -10,7 +10,7 @@ import { resolveReferences } from "../openapi/references.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { OPENAPI_PATH } from "./api/paths.ts";
 import { asciiSlugify } from "./mcp/discovery.ts";
-import { AGENT_SKILLS_DIR } from "./skills.ts";
+import { AGENT_SKILLS_DIR, servesSkillsIndex } from "./skills.ts";
 import type { SkillArtifact } from "./skills.ts";
 
 /**
@@ -86,7 +86,7 @@ export const hasAiCatalog = (config: ResolvedConfig): boolean =>
   (config.agents.mcp.enabled ||
     config.agents.api ||
     config.agents.llmsTxt.enabled ||
-    Boolean(config.agents.skills) ||
+    servesSkillsIndex(config) ||
     resolveReferences(config).length > 0);
 
 /**
@@ -118,7 +118,10 @@ const NAMES_DOCS = /\b(?:docs|documentation)$/iu;
  * reads "the Acme documentation" and "Acme Docs" reads "the Acme Docs", not
  * "the Acme Docs docs".
  */
-const docsPhrase = (title: string, noun: "docs" | "documentation"): string =>
+export const docsPhrase = (
+  title: string,
+  noun: "docs" | "documentation"
+): string =>
   NAMES_DOCS.test(title.trim()) ? `the ${title}` : `the ${title} ${noun}`;
 
 const entrySeeds = (

package/src/ai/ask-context.ts

@@ -228,6 +228,17 @@ 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).";
 
+/**
+ * Appended when the endpoint gives the model the docs tools (see
+ * `ask-tools.ts`): the excerpts are a head start, not the whole of the docs.
+ */
+const TOOL_INSTRUCTION =
+  "You can also search the documentation yourself. When the excerpts don't fully answer the question, call search_docs with a focused query to find other pages, and read_page to read a page in full (one an excerpt cuts off, say) before you answer. Treat tool results exactly like the excerpts: answer only from them, and cite the pages you drew from the same way.";
+
+/** Said instead of the excerpts when retrieval found none but tools can look. */
+const NO_EXCERPTS_WITH_TOOLS =
+  "No documentation excerpts matched this question up front. Use search_docs to look before you answer.";
+
 /** The non-empty user turns, oldest first. Assistant turns never seed retrieval. */
 const userTurns = (messages: AskMessage[]): string[] =>
   messages
@@ -591,6 +602,78 @@ export const sectionExcerpt = (
   max: number
 ): string => excerptPage(parsePage(content), query, max);
 
+// One Orama index per snapshot, shared by the grounding function and the
+// docs tools so a cold endpoint builds it once.
+const indexes = new WeakMap<AskData, ReturnType<typeof buildOramaIndex>>();
+
+/** The search index over an assistant snapshot, built on first use. */
+export const askIndex = (data: AskData): ReturnType<typeof buildOramaIndex> => {
+  let index = indexes.get(data);
+  if (!index) {
+    index = buildOramaIndex(data.documents, data.defaultLocale);
+    indexes.set(data, index);
+  }
+  return index;
+};
+
+/** The page the reader is on, and the search filters it implies. */
+export interface ReaderScope {
+  current: OramaDoc | undefined;
+  filters: { locale: string | undefined; version: string | undefined };
+}
+
+// The snapshot's locale codes, keyed lowercase, built once per snapshot.
+const localeCodes = new WeakMap<AskData, Map<string, string>>();
+
+/**
+ * The locale a path's first segment names (`/ja` or `/ja/pricing` → `ja`),
+ * when it's one the snapshot's documents carry: a page outside the docs,
+ * like a localized landing page, still says which language it's in.
+ */
+const pathLocale = (data: AskData, path: string): string | undefined => {
+  let codes = localeCodes.get(data);
+  if (!codes) {
+    codes = new Map<string, string>();
+    for (const { locale } of data.documents) {
+      if (locale) {
+        codes.set(locale.toLowerCase(), locale);
+      }
+    }
+    localeCodes.set(data, codes);
+  }
+  const [, first = ""] = normalizeRoute(path).split("/");
+  return first ? codes.get(first.toLowerCase()) : undefined;
+};
+
+/**
+ * Where the reader is: their page, when it's in the snapshot, and the locale
+ * and docs version retrieval keeps to. A page the snapshot doesn't have (the
+ * homepage, a custom page, or none at all from a cross-origin caller) keeps
+ * to the locale its path's first segment names, or the default locale, so
+ * translations of every page don't crowd each other out. Without a page, a
+ * versioned site grounds in the current docs rather than every archived copy
+ * of each page.
+ */
+export const readerScope = (
+  data: AskData,
+  byRoute: ReadonlyMap<string, OramaDoc>,
+  page?: AskPage
+): ReaderScope => {
+  const current = page?.path
+    ? byRoute.get(normalizeRoute(page.path))
+    : undefined;
+  const locale = current
+    ? current.locale
+    : (page?.path && pathLocale(data, page.path)) || data.defaultLocale;
+  return {
+    current,
+    filters: {
+      locale: locale || undefined,
+      version: data.versioned ? (current?.version ?? "") : undefined,
+    },
+  };
+};
+
 /**
  * Build the request-time grounding function for the assistant endpoint.
  *
@@ -607,20 +690,22 @@ export const sectionExcerpt = (
  *
  * `options.retrieval` (the `ai.assistant.retrieval` config) sizes how much
  * documentation each question carries; omitted fields keep today's defaults.
+ *
+ * `options.tools` says the endpoint also hands the model the docs tools: the
+ * prompt then says so, and a question retrieval found nothing for still gets
+ * a grounded prompt, since the model can go and search.
  */
 export const createAskContext = (
   data: AskData,
-  options?: { instructions?: string; retrieval?: AskRetrievalOptions }
+  options?: {
+    instructions?: string;
+    retrieval?: AskRetrievalOptions;
+    tools?: boolean;
+  }
 ): ((
   messages: AskMessage[],
   page?: AskPage
 ) => Promise<string | undefined>) => {
-  let dbPromise: Promise<Awaited<ReturnType<typeof buildOramaIndex>>> | null =
-    null;
-  const index = () => {
-    dbPromise ??= buildOramaIndex(data.documents, data.defaultLocale);
-    return dbPromise;
-  };
   const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
   // Section splitting and tokenizing are per page, not per question, so each
   // page is parsed on first use and reused for the life of the endpoint.
@@ -633,9 +718,12 @@ export const createAskContext = (
     }
     return page;
   };
-  const instruction = options?.instructions
-    ? `${BASE_INSTRUCTION}\n\n${options.instructions}`
+  const base = options?.tools
+    ? `${BASE_INSTRUCTION} ${TOOL_INSTRUCTION}`
     : BASE_INSTRUCTION;
+  const instruction = options?.instructions
+    ? `${base}\n\n${options.instructions}`
+    : base;
   const maxResults = options?.retrieval?.maxResults ?? MAX_RESULTS;
   const excerptChars = options?.retrieval?.excerptChars ?? EXCERPT_CHARS;
   const contextBudget = options?.retrieval?.contextBudget ?? CONTEXT_BUDGET;
@@ -652,16 +740,9 @@ export const createAskContext = (
     const [query = ""] = queries;
 
     // The current page anchors retrieval to its locale and docs version, and
-    // is injected first. Without one, a versioned site grounds in the
-    // current docs rather than every archived copy of each page.
-    const current = page?.path
-      ? byRoute.get(normalizeRoute(page.path))
-      : undefined;
-    const db = await index();
-    const filters = {
-      locale: current?.locale || undefined,
-      version: data.versioned ? (current?.version ?? "") : undefined,
-    };
+    // is injected first.
+    const { current, filters } = readerScope(data, byRoute, page);
+    const db = await askIndex(data);
     const hits = interleave(
       await Promise.all(
         queries.map((text) => queryOramaIndex(db, text, maxResults, filters))
@@ -700,7 +781,9 @@ export const createAskContext = (
     }
 
     if (sections.length === 0) {
-      return;
+      return options?.tools
+        ? `${instruction}\n\n${NO_EXCERPTS_WITH_TOOLS}`
+        : undefined;
     }
     return `${instruction}\n\n<docs>\n${sections.join("\n\n")}\n</docs>`;
   };

package/src/ai/ask-data.ts

@@ -36,6 +36,12 @@ export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
       if (versioned) {
         document.version = doc.version;
       }
+      if (doc.boost !== undefined) {
+        document.boost = doc.boost;
+      }
+      if (doc.keywords) {
+        document.keywords = doc.keywords;
+      }
       return document;
     }),
     site: project.config.deployment.options.site ?? null,

package/src/ai/ask-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * What one request to the assistant's generated route (`/api/ask`) may carry.
+ * The route answers a longer conversation with a `400` (see
+ * `askEndpointTemplate`), so the panel's client (`useAssistant`) sends only
+ * the latest turns that fit. The endpoint is unauthenticated, so the limits
+ * bound what one request can spend against the model.
+ */
+
+/** The most messages, questions and answers together, one request sends. */
+export const ASK_MAX_MESSAGES = 40;
+
+/** The most characters the messages take as JSON (`JSON.stringify`). */
+export const ASK_MAX_MESSAGES_CHARS = 24_000;

package/src/ai/ask-tools.ts

@@ -0,0 +1,142 @@
+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 type { AskData, AskPage, ReaderScope } from "./ask-context.ts";
+
+/**
+ * The assistant's docs tools: what lets it look beyond the excerpts the
+ * endpoint injects up front. `search_docs` runs the same Orama search the
+ * grounding does, scoped to the reader's language and docs version;
+ * `read_page` returns a whole page, for when an excerpt stops short of the
+ * answer. Both read the assistant snapshot the endpoint already imports, so
+ * they add no build output and no network call.
+ *
+ * The generated `/api/ask` route passes them to `streamText` with a step cap
+ * ({@link ASK_MAX_STEPS}), so the model can search, read, and then answer
+ * within one request.
+ */
+
+/**
+ * The most model steps one answer may take: up to four rounds of tool calls,
+ * then the answer. Enough to search, read a page or two, and search again,
+ * while bounding what one question can spend.
+ */
+export const ASK_MAX_STEPS = 5;
+
+/** Pages one search returns. */
+const SEARCH_RESULTS = 5;
+
+/** Characters of each search result's most relevant excerpt. */
+const SEARCH_EXCERPT_CHARS = 700;
+
+/** Characters of a page `read_page` returns; a longer page is cut here. */
+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}`;
+
+/**
+ * Search the docs for `query` within the reader's scope: the most relevant
+ * excerpt of each of the top pages, or a note that nothing matched.
+ */
+export const searchDocs = async (
+  data: AskData,
+  scope: ReaderScope,
+  query: string
+): Promise<string> => {
+  const hits = await queryOramaIndex(
+    await askIndex(data),
+    query,
+    SEARCH_RESULTS,
+    scope.filters
+  );
+  if (hits.length === 0) {
+    return `No pages matched "${query}". Try other words, or a broader query.`;
+  }
+  return hits
+    .map((doc) =>
+      block(doc, sectionExcerpt(doc.content, query, SEARCH_EXCERPT_CHARS))
+    )
+    .join("\n\n");
+};
+
+/**
+ * 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.
+ */
+const routeOf = (data: AskData, requested: string): string => {
+  let path = requested.trim();
+  if (data.site && path.startsWith(data.site)) {
+    path = path.slice(data.site.replace(/\/$/u, "").length) || "/";
+  }
+  path = path.replace(/[?#].*$/u, "");
+  return normalizeRoute(path.startsWith("/") ? path : `/${path}`);
+};
+
+/** A whole page by route, cut at {@link PAGE_CHARS}, or a note that it doesn't exist. */
+export const readPage = (
+  data: AskData,
+  byRoute: ReadonlyMap<string, OramaDoc>,
+  requested: string
+): string => {
+  const route = routeOf(data, requested);
+  const doc = byRoute.get(route);
+  if (!doc) {
+    return `There is no page at ${route}. Use search_docs to find the right one.`;
+  }
+  const text =
+    doc.content.length > PAGE_CHARS
+      ? `${doc.content.slice(0, PAGE_CHARS)}\n\n[The page continues; this is its first ${PAGE_CHARS.toLocaleString("en-US")} characters.]`
+      : doc.content;
+  return block(doc, text);
+};
+
+/**
+ * The tools for one request, given the page the reader is on. Built per
+ * request because the search scope follows the reader's locale and version.
+ */
+export const createAskTools = (data: AskData) => {
+  const byRoute = new Map(data.documents.map((doc) => [doc.route, doc]));
+  return (page?: AskPage) => {
+    const scope = readerScope(data, byRoute, page);
+    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).",
+        execute: ({ route }) => Promise.resolve(readPage(data, byRoute, route)),
+        inputSchema: jsonSchema<{ route: string }>({
+          additionalProperties: false,
+          properties: {
+            route: {
+              description: "The page's route, such as /docs/getting-started.",
+              type: "string",
+            },
+          },
+          required: ["route"],
+          type: "object",
+        }),
+      }),
+      search_docs: tool({
+        description:
+          "Search this project's documentation. Returns the most relevant excerpt of each matching page, headed by its title and route.",
+        execute: ({ query }) => searchDocs(data, scope, query),
+        inputSchema: jsonSchema<{ query: string }>({
+          additionalProperties: false,
+          properties: {
+            query: {
+              description:
+                "A few focused keywords, such as the feature or option the question is about.",
+              type: "string",
+            },
+          },
+          required: ["query"],
+          type: "object",
+        }),
+      }),
+    };
+  };
+};