blume 2.0.1 → 2.0.3

package/src/ai/component-markdown.ts

@@ -4,6 +4,7 @@ import { mdxToMdast } from "satteri";
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
 import { MDX_FEATURES } from "../markdown/features.ts";
+import { readStaticExpression } from "./static-expression.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -44,11 +45,19 @@ interface MdxAttribute {
 
 /** A single source replacement: `[start, end)` byte range → `text`. */
 interface Splice {
+  /**
+   * The range is a flow (block-level) element, so the line after it must
+   * start a block of its own.
+   */
+  block: boolean;
   end: number;
   start: number;
   text: string;
 }
 
+/** Text that continues on the very next line, with no blank line between. */
+const NEXT_LINE_TEXT = /^[\t ]*\n[\t ]*\S/u;
+
 /**
  * A statically-recovered data value. Parsed front matter and evaluated
  * attribute literals are both plain data — scalars, dates, arrays, and
@@ -135,33 +144,13 @@ export type ComponentMarkdown = (
 ) => string | null;
 
 /**
- * Statically evaluate an MDX attribute expression (`prop={...}`). Component
- * data props are object/array/number literals in practice; evaluation runs at
- * build time over the author's own content — the same trust level as the MDX
- * itself, which Astro compiles and executes. The page's `frontmatter` is in
- * scope, mirroring what Astro provides an MDX body at render time, so
- * `prop={frontmatter.status}` resolves; expressions that reference imports or
- * other scope throw and report as not evaluable.
+ * Read an element's attributes into a plain props object. An expression
+ * attribute (`prop={...}`) is read as literal data and never executed (see
+ * `static-expression.ts`): the downleveler also runs over plain `.md` pages
+ * and remote content, which nothing else executes. `prop={frontmatter.status}`
+ * resolves against the page's front matter, as it does when Astro renders
+ * the page; anything else — a call, an import — marks the props lossy.
  */
-const evaluateExpression = (
-  raw: string,
-  frontmatter: Record<string, EvaluatedValue> | undefined
-) => {
-  try {
-    // Build-time eval of the author's own attribute literals; a throw falls
-    // back to leaving the JSX verbatim.
-    // oxlint-disable-next-line no-new-func
-    const value: EvaluatedValue = new Function(
-      "frontmatter",
-      `"use strict"; return (${raw});`
-    )(frontmatter);
-    return { ok: true, value };
-  } catch {
-    return { ok: false, value: undefined };
-  }
-};
-
-/** Evaluate an element's attributes into a plain props object. */
 const readProps = (
   node: MdastNode,
   frontmatter: Record<string, EvaluatedValue> | undefined
@@ -180,7 +169,7 @@ const readProps = (
     } else if (isString(attribute.value)) {
       props[attribute.name] = attribute.value;
     } else {
-      const result = evaluateExpression(attribute.value.value, frontmatter);
+      const result = readStaticExpression(attribute.value.value, frontmatter);
       if (result.ok) {
         props[attribute.name] = result.value;
       } else {
@@ -208,14 +197,24 @@ const applySplices = (text: string, splices: Splice[]): string => {
     const lineStart = result.lastIndexOf("\n", splice.start - 1) + 1;
     const prefix = result.slice(lineStart, splice.start);
     const indent = /^[\t ]+$/u.test(prefix) ? prefix : "";
+    // The JSX's closing tag ended its block; the Markdown standing in for it
+    // doesn't. Text on the very next line would read as a lazy continuation
+    // of a blockquote or list item (`> Body` then `Next.` joins the quote),
+    // so a blank line keeps it out.
+    const spliced =
+      splice.block &&
+      splice.text !== "" &&
+      NEXT_LINE_TEXT.test(result.slice(splice.end))
+        ? `${splice.text}\n`
+        : splice.text;
     const replacement = indent
-      ? splice.text
+      ? spliced
           .split("\n")
           .map((line, index) =>
             index === 0 || line === "" ? line : `${indent}${line}`
           )
           .join("\n")
-      : splice.text;
+      : spliced;
     result =
       result.slice(0, splice.start) + replacement + result.slice(splice.end);
   }
@@ -888,15 +887,21 @@ const renderSlice = (
   const splices: Splice[] = [];
   // oxlint-disable-next-line no-use-before-define
   collectSplices(walk, nodes, splices);
+  // Start the slice at its line's indent, so a component that opens the
+  // slice is indented like the lines after it once replaced (see
+  // `applySplices`) and dedents with them; the final trim drops that indent
+  // from the first line again.
+  const indent = indentAt(walk.source, start);
+  const from = start - (indent ?? 0);
   const spliced = applySplices(
-    walk.source.slice(start, end),
+    walk.source.slice(from, end),
     splices.map((splice) => ({
       ...splice,
-      end: splice.end - start,
-      start: splice.start - start,
+      end: splice.end - from,
+      start: splice.start - from,
     }))
   );
-  return dedent(spliced, indentAt(walk.source, start)).trim();
+  return dedent(spliced, indent).trim();
 };
 
 /** The element's body as Markdown: the slice covering all of its children. */
@@ -996,6 +1001,7 @@ const collectSplices = (
     const text = hasOffsets(node) ? downlevelComponentNode(node, walk) : null;
     if (text !== null && hasOffsets(node)) {
       out.push({
+        block: node.type === "mdxJsxFlowElement",
         end: node.position.end.offset,
         start: node.position.start.offset,
         text,
@@ -1015,10 +1021,10 @@ const collectSplices = (
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
  *
- * `frontmatter` is the page's parsed front-matter data. It is put in scope
- * when evaluating attribute expressions — so `prop={frontmatter.status}`
- * resolves the way it does when Astro renders the page — and handed to
- * serializers on their context.
+ * `frontmatter` is the page's parsed front-matter data. Attribute
+ * expressions that reference it — `prop={frontmatter.status}` — resolve the
+ * way they do when Astro renders the page, and it is handed to serializers on
+ * their context. Expressions are read as literal data, never executed.
  */
 export const downlevelComponents = (
   source: string,

package/src/ai/link-headers.ts

@@ -5,7 +5,11 @@ import {
   AI_CATALOG_TYPE,
   hasAiCatalog,
 } from "./ai-catalog.ts";
-import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  hasApiCatalog,
+} from "./api-catalog.ts";
 import { OPENAPI_PATH } from "./api/paths.ts";
 
 /**
@@ -29,23 +33,33 @@ import { OPENAPI_PATH } from "./api/paths.ts";
  * headers. Targets are
  * root-relative under `deployment.base` — RFC 8288 resolves them against the
  * request URL. Returns null when nothing is advertisable.
+ *
+ * `surface` is where the header is sent. A deployed site (`"build"`) serves
+ * every target. The dev server (`"dev"`) serves the routes — the JSON API's
+ * OpenAPI document and the Markdown mirror — but not the files `blume build`
+ * writes after the build (the API and AI catalogs, `agent-readability.json`,
+ * `llms.txt`), so its header leaves those out rather than point agents at
+ * 404s.
  */
 export const buildHomeLinkHeader = (
   config: ResolvedConfig,
-  routePaths: readonly string[]
+  routePaths: readonly string[],
+  surface: "build" | "dev" = "build"
 ): string | null => {
   const deployBase = normalizeBasePath(config.deployment.options.base);
+  const artifacts = surface === "build";
   const links: string[] = [];
   // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
-  // well-known catalog.
-  if (hasApiCatalog(config)) {
+  // well-known catalog. Its type carries the RFC 9727 profile, whose quotes
+  // are escaped inside the quoted `type` value (RFC 8288 quoted-string).
+  if (artifacts && hasApiCatalog(config)) {
     links.push(
-      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="application/linkset+json"`
+      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="${API_CATALOG_TYPE.replaceAll('"', String.raw`\"`)}"`
     );
   }
   // The ai-catalog spec's own relation for its well-known document, the
   // header form of the `<link rel="ai-catalog">` every page carries.
-  if (hasAiCatalog(config)) {
+  if (artifacts && hasAiCatalog(config)) {
     links.push(
       `<${deployBase}${AI_CATALOG_PATH}>; rel="ai-catalog"; type="${AI_CATALOG_TYPE}"`
     );
@@ -57,12 +71,12 @@ export const buildHomeLinkHeader = (
       `<${deployBase}${OPENAPI_PATH}>; rel="service-desc"; type="application/json"`
     );
   }
-  if (config.agents.agentReadability) {
+  if (artifacts && config.agents.agentReadability) {
     links.push(
       `<${deployBase}/agent-readability.json>; rel="describedby"; type="application/json"`
     );
   }
-  if (config.agents.llmsTxt.enabled) {
+  if (artifacts && config.agents.llmsTxt.enabled) {
     links.push(
       `<${deployBase}/llms.txt>; rel="describedby"; type="text/plain"`
     );

package/src/ai/llms.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } 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";
@@ -17,14 +17,22 @@ import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
-// with or without a `site` (the mcp.json convention) — so the emitted URL
-// matches where the page is served. Encoded like the sitemap: a route with
-// spaces or non-ASCII must still yield a valid Markdown link.
+// with or without a `site` (the mcp.json convention), and even over a route
+// that starts with the base's own name — so the emitted URL matches where the
+// page is served. Encoded like the sitemap: a route with spaces or non-ASCII
+// must still yield a valid Markdown link.
 const pageUrl = (route: string, site?: string, base = ""): string => {
-  const path = withBasePath(base, route);
+  const path = mountBasePath(base, route);
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
+/**
+ * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
+ * — closes or nests the text early, and the line stops being a link.
+ */
+const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
+
 /** Inputs only the build has: the published skills, collected once per build. */
 export interface LlmsIndexOptions {
   /**
@@ -176,7 +184,7 @@ export const buildLlmsIndex = (
   const line = (page: PageRecord): string => {
     seen.add(page.route);
     const summary = page.description ? `: ${page.description}` : "";
-    return `- [${page.title}](${pageUrl(page.route, site, base)})${summary}`;
+    return `- [${linkText(page.title)}](${pageUrl(page.route, site, base)})${summary}`;
   };
 
   // One nav level -> Markdown blocks: the level's loose pages as a link list,
@@ -259,7 +267,10 @@ export const buildLlmsIndex = (
     blocks.push(
       "## RSS Feeds",
       feeds
-        .map((feed) => `- [${feed.title}](${pageUrl(feed.path, site, base)})`)
+        .map(
+          (feed) =>
+            `- [${linkText(feed.title)}](${pageUrl(feed.path, site, base)})`
+        )
         .join("\n")
     );
   }
@@ -312,10 +323,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
           source: raw,
           sourcePath: page.sourcePath,
         });
-        // Relative page links too: a reader of one flat file has no page URL
-        // to resolve `./install` against.
-        raw = rewriteLinks(raw, page);
       }
+      // Page links too: a reader of one flat file has no page URL to resolve
+      // `./install` against, and `/install` needs the base the site is
+      // served under.
+      raw = rewriteLinks(raw, page);
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.

package/src/ai/markdown.ts

@@ -8,6 +8,7 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
+import { advertisedConfig, servesMcp } from "./agent-surface.ts";
 import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
@@ -80,13 +81,14 @@ export const buildRawMarkdown = async (
           source: text,
           sourcePath: route.sourcePath,
         });
-        // `./install` means the page's sibling, not whatever the `.md` URL
-        // an agent fetched resolves it to.
-        text = rewriteLinks(text, {
-          route: route.path,
-          sourcePath: route.sourcePath,
-        });
       }
+      // `./install` means the page's sibling, not whatever the `.md` URL an
+      // agent fetched resolves it to, and `/install` gains the base and the
+      // page's locale the rendered link has — remote content included.
+      text = rewriteLinks(text, {
+        route: route.path,
+        sourcePath: route.sourcePath,
+      });
       const source = applyAgentVisibility(text);
       // The `.md` variant keeps the front-matter block in the output, but its
       // data must also be in scope for `prop={frontmatter.*}` expressions.
@@ -97,19 +99,29 @@ export const buildRawMarkdown = async (
     })
   );
   const map = Object.fromEntries(entries);
+  const userPages = project.context.pagesRoot
+    ? await discoverPages(project.context.pagesRoot)
+    : [];
   // A landing-page homepage (user `.astro` page, or no home route at all) has
   // no Markdown source, but agents negotiating `Accept: text/markdown` on `/`
   // still expect a Markdown answer. The llms.txt index — the machine-readable
   // representation of the site a landing page fronts — becomes its mirror, so
-  // `/index.md` always exists (see `markdownRoutePaths`).
+  // `/index.md` always exists (see `markdownRoutePaths`). Like llms.txt, it
+  // leaves out an MCP server a page's route kept from being generated.
   if (!map["/"]) {
-    map["/"] = { mdx: buildLlmsIndex(project) };
+    map["/"] = {
+      mdx: buildLlmsIndex({
+        ...project,
+        config: advertisedConfig(project.config, {
+          mcp: servesMcp(project, userPages),
+          // Skills are collected at the end of the build, after this runs.
+          skills: Boolean(project.config.agents.skills),
+        }),
+      }),
+    };
   }
   // The generated changelog index has no source either; its release list is
   // its mirror, so `/changelog.md` and `get_page` answer as the page does.
-  const userPages = project.context.pagesRoot
-    ? await discoverPages(project.context.pagesRoot)
-    : [];
   if (hasGeneratedChangelog(project, userPages)) {
     map[CHANGELOG_INDEX_ROUTE] = { mdx: buildChangelogIndexMarkdown(project) };
   }

package/src/ai/mcp/discovery.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import { trimChar } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
@@ -18,7 +18,7 @@ export interface McpDiscoveryInput {
 const serverUrl = (input: McpDiscoveryInput): string => {
   // The endpoint is a generated Astro page, so it's served under
   // `deployment.base` like every other route (the sitemap/llms.txt convention).
-  const path = withBasePath(input.base, input.route);
+  const path = mountBasePath(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 ? absoluteUrl(input.site, path) : path;

package/src/ai/mcp/query.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
 
 import {
+  mountBasePath,
   normalizeRoute as normalizePageRoute,
   stripBasePath,
-  withBasePath,
 } from "../../core/base-path.ts";
 import { absoluteUrl } from "../../core/site-url.ts";
 import { trimEnd } from "../../core/trim.ts";
@@ -244,7 +244,7 @@ export const normalizeRoute = (input: string, data: McpData): string => {
 export const urlFor = (route: string, data: McpData): string => {
   // Routes are base-less manifest paths; layer `deployment.base` on top so the
   // URL matches where the page is served (the sitemap/llms.txt convention).
-  const path = withBasePath(data.base, route);
+  const path = mountBasePath(data.base, 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 data.site ? absoluteUrl(data.site, path) : path;

package/src/ai/mcp/server.ts

@@ -2,7 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
-  CallToolRequestSchema,
+  ErrorCode,
   ListResourcesRequestSchema,
   ListToolsRequestSchema,
   McpError,
@@ -10,7 +10,8 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
+import { readCappedText } from "../../core/request-body.ts";
 import type { McpData } from "./data.ts";
 import {
   createIndexProvider,
@@ -42,6 +43,12 @@ const RESOURCE_MIME_TYPE = "text/markdown";
 const RESOURCE_NOT_FOUND = -32_002;
 /** URI scheme for page resources when no `deployment.site` is configured. */
 const LOCAL_RESOURCE_SCHEME = "blume:";
+/**
+ * The largest request body the HTTP endpoint reads. A JSON-RPC call to these
+ * tools is a few hundred bytes; the cap keeps one oversized POST from being
+ * buffered whole, as the assistant route's does.
+ */
+const MCP_BODY_LIMIT_BYTES = 65_536;
 
 const CORS_HEADERS = {
   "Access-Control-Allow-Headers":
@@ -97,7 +104,7 @@ interface PageResource {
 const resourceUri = (route: string, data: McpData): string =>
   data.site
     ? urlFor(route, data)
-    : `${LOCAL_RESOURCE_SCHEME}${withBasePath(data.base, route)}`;
+    : `${LOCAL_RESOURCE_SCHEME}${mountBasePath(data.base, route)}`;
 
 /** The `pages` key a resource URI (either form, or a bare route) names. */
 const resourceRoute = (uri: string, data: McpData): string =>
@@ -108,6 +115,20 @@ const resourceRoute = (uri: string, data: McpData): string =>
     data
   );
 
+/**
+ * The `tools/call` params, as far as the server reads them before dispatch:
+ * each tool validates its own `arguments` against `TOOL_INPUTS`.
+ */
+const TOOL_CALL_PARAMS = z.object({
+  arguments: z.record(z.string(), z.unknown()).optional(),
+  name: z.string(),
+});
+
+/** A tool call's `arguments` object, before the tool's own validation. */
+type ToolArguments = NonNullable<
+  z.output<typeof TOOL_CALL_PARAMS>["arguments"]
+>;
+
 /** A tool call's text result, marked as an error when `isError` is set. */
 const text = (value: string, isError = false) => {
   const content = [{ text: value, type: "text" as const }];
@@ -165,9 +186,7 @@ export const buildServer = (
     };
   });
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { arguments: args = {}, name } = request.params;
-
+  const callTool = async (name: string, args: ToolArguments) => {
     if (name === "search_docs") {
       const results = await searchDocs(
         data,
@@ -206,12 +225,44 @@ export const buildServer = (
       return text(JSON.stringify(result.navigation, null, 2));
     }
 
-    return text(`Unknown tool: ${name}`, true);
-  });
+    // The MCP spec answers an unknown tool with a protocol error, not a
+    // failed tool result.
+    throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+  };
+
+  // `tools/call` goes through the fallback handler rather than a registered
+  // one: the SDK parses a registered handler's request against its own
+  // schema first and reports a malformed call (`arguments` that aren't an
+  // object) as -32603 Internal error carrying a raw Zod dump. Reading the
+  // params here answers it as -32602 Invalid params with a short message.
+  server.fallbackRequestHandler = async (request) => {
+    if (request.method !== "tools/call") {
+      throw new McpError(ErrorCode.MethodNotFound, "Method not found");
+    }
+    const params = TOOL_CALL_PARAMS.safeParse(request.params);
+    if (!params.success) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "Invalid tools/call params: `name` must be a string and `arguments`, when given, an object."
+      );
+    }
+    return await callTool(params.data.name, params.data.arguments ?? {});
+  };
 
   return server;
 };
 
+/** A JSON-RPC error response the transport would send, for errors raised before it runs. */
+const jsonRpcError = (
+  status: number,
+  code: number,
+  message: string
+): Response =>
+  Response.json(
+    { error: { code, message }, id: null, jsonrpc: "2.0" },
+    { headers: CORS_HEADERS, status }
+  );
+
 /**
  * Build a stateless Streamable-HTTP MCP request handler from a data snapshot.
  *
@@ -239,6 +290,26 @@ export const createMcpFetchHandler = (
       });
     }
 
+    // The transport would read the body with `request.json()`, buffering
+    // whatever a client sends; read it under the cap first and hand the
+    // transport a copy.
+    let forwarded = request;
+    if (request.method === "POST") {
+      const body = await readCappedText(request, MCP_BODY_LIMIT_BYTES);
+      if (body === undefined) {
+        return jsonRpcError(
+          413,
+          ErrorCode.InvalidRequest,
+          "Request too large: the body must be at most 64 KB."
+        );
+      }
+      forwarded = new Request(request.url, {
+        body,
+        headers: request.headers,
+        method: "POST",
+      });
+    }
+
     const server = buildServer(data, index);
     const transport = new WebStandardStreamableHTTPServerTransport({
       enableJsonResponse: true,
@@ -248,7 +319,7 @@ export const createMcpFetchHandler = (
       sessionIdGenerator: undefined,
     });
     await server.connect(transport);
-    const response = await transport.handleRequest(request);
+    const response = await transport.handleRequest(forwarded);
 
     const headers = new Headers(response.headers);
     for (const [key, value] of Object.entries(CORS_HEADERS)) {

package/src/ai/openapi-components.ts

@@ -1,3 +1,4 @@
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
 import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
@@ -20,10 +21,14 @@ const inlineText = (text: string): string =>
     .replaceAll(/\s+/gu, " ")
     .replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
 
-/** One operation as a link, for the tag listings. */
+/**
+ * One operation as a link, for the tag listings. `href` is the operation's
+ * served URL: its route under the deployment base.
+ */
 const listItem = (
   signature: string,
-  operation: Pick<ApiOperationRef, "deprecated" | "route" | "summary">
+  href: string,
+  operation: Pick<ApiOperationRef, "deprecated" | "summary">
 ): string => {
   const tail = [
     // Title-like summaries ("Get a flag") need their own period before the
@@ -33,7 +38,7 @@ const listItem = (
   ]
     .filter(Boolean)
     .join(" ");
-  return `- [${inlineCode(signature)}](${linkDestination(operation.route)})${tail ? ` — ${tail}` : ""}`;
+  return `- [${inlineCode(signature)}](${linkDestination(href)})${tail ? ` — ${tail}` : ""}`;
 };
 
 /**
@@ -60,9 +65,16 @@ const listItem = (
  * endpoint and what it does is the part that was missing altogether.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
- * API reference, in which case every serializer declines.
+ * API reference, in which case every serializer declines. `deployBase` is the
+ * configured `deployment.base`: operation routes carry `basePath` but not it,
+ * and the links written here are made after the agent surfaces rebase the
+ * page's own links, so they take it here, as the rendered page's do.
  */
-export const openapiComponentSerializers = (specs: OpenApiData) => {
+export const openapiComponentSerializers = (
+  specs: OpenApiData,
+  deployBase?: string
+) => {
+  const base = normalizeBasePath(deployBase);
   const spec = (source: EvaluatedValue) =>
     isString(source) ? specOf(specs, source) : undefined;
 
@@ -97,7 +109,11 @@ export const openapiComponentSerializers = (specs: OpenApiData) => {
       const items = Object.values(data.operations)
         .filter((operation) => operation.tagSlug === tag)
         .map((operation) =>
-          listItem(operationSignature(data, operation), operation)
+          listItem(
+            operationSignature(data, operation),
+            mountBasePath(base, operation.route),
+            operation
+          )
         );
       return items.length > 0 ? items.join("\n") : null;
     },