blume 1.2.1 → 1.3.1

package/skills/blume-migrate/SKILL.md

@@ -9,6 +9,8 @@ Blume is a **markdown-first** documentation framework on Astro/Vite. You drop Ma
 
 Your job is to convert a source docs repo into an **idiomatic** Blume project — not a 1:1 transliteration. Read this file, detect the source framework, open the matching `references/<framework>.md` for the exact mappings, and work the loop below. Report everything you drop or approximate.
 
+Throughout this skill (including the `references/` files), **`<skill>` means the absolute path of the directory containing this SKILL.md** — resolve it from wherever you read this file (e.g. `node_modules/blume/skills/blume-migrate` or `.claude/skills/blume-migrate`). It is a placeholder to substitute, never a literal path.
+
 ## Migration philosophy
 
 - **Target idiomatic Blume, not a mechanical port.** Prefer filesystem-derived navigation over an exhaustive explicit `navigation.sidebar`. Prefer `:::` directives over JSX callouts. Prefer Blume defaults over restating them in config.
@@ -62,7 +64,7 @@ The single biggest shift for most sources — especially Mintlify — is that **
 `defineConfig({...})` — every field optional, all with defaults:
 
 - **Site:** `title`, `description`, `logo` (string SVG, or `{ image: string | { light, dark, alt }, text, href }`), `banner` (`{ content, link, dismissible, id }` — no color/type). A logo renders beside `title` in the header, so a **wordmark logo doubles the brand** ("Acme Acme") — set `text: ""` to render the mark alone. **Prefer the string form over `{ light, dark }`:** if you have the logo SVG locally and it's monochrome (solid black or white), rewrite its `fill`/`stroke` to `currentColor` and use `logo: "/logo.svg"` — it then inherits the theme's text color and adapts to light/dark automatically, so you don't need separate light/dark files.
-- **`theme`:** `accent` (a color string for both modes, or `{ light, dark }` per mode), `action` (color), `mode` (`light`/`dark`/`system`), `radius`, `fonts` (`{ body, display, mono }` — curated Google-font slugs), `background` and `backgroundImage` (each a string, or `{ light, dark }` per mode). The old `accentDark`/`backgroundDark`/`backgroundImageDark` fields were **merged into these per-mode objects** — a bare string still applies to both modes, so only reach for `{ light, dark }` when the two modes differ. There is **no** `theme.strict` and **no** `theme.css` config field — custom CSS goes in a project-root **`theme.css` file** (auto-picked-up), and a source's "strict appearance" flags drop.
+- **`theme`:** `accent` (a color string for both modes, or `{ light, dark }` per mode), `action` (color), `mode` (`light`/`dark`/`system`), `radius`, `fonts` (`{ body, display, mono }` — each a curated Google-font slug, a `{ name, provider?, weights? }` object for any Google/Fontsource/Bunny/Fontshare family, or `{ name, variants: [{ src, weight?, style? }] }` for local font files), `background` and `backgroundImage` (each a string, or `{ light, dark }` per mode). The old `accentDark`/`backgroundDark`/`backgroundImageDark` fields were **merged into these per-mode objects** — a bare string still applies to both modes, so only reach for `{ light, dark }` when the two modes differ. There is **no** `theme.strict` and **no** `theme.css` config field — custom CSS goes in a project-root **`theme.css` file** (auto-picked-up), and a source's "strict appearance" flags drop.
 - **`content`:** `root` (default `"docs"`, relative to the project dir where `blume` runs), `include`/`exclude` (arrays of globs **relative to `content.root`**; defaults `["**/*.{md,mdx}"]` / `["**/_*", "**/.*"]`), `sources` (staged sources: `filesystem`, `github-releases`, `notion`, `sanity`, `mdx-remote`, `custom` — OpenAPI is **not** one of these; it's the top-level `openapi` field), `pages` (custom `.astro` dir), `defaultType`. When docs sit directly under the project dir (no `docs/` subfolder), set `root` there and **scope `include` to the real content folders** instead of scanning everything — `references/monorepo.md` §1.
 - **`basePath`** (top-level): a site-wide mount point (e.g. `"/docs"`) prepended to **every** route while staying invisible to the sidebar (no wrapper group). This is the right target for a source that served all docs under a prefix (Docusaurus `routeBasePath`, a Fumadocs `baseUrl` of `/docs`) — distinct from a per-source `prefix` (which adds a nav group) and from `deployment.base` (host subdirectory).
 - **`navigation`:** `tabs`, `selectors`, `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo`. **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see "Config-declared nesting" above).
@@ -70,7 +72,7 @@ The single biggest shift for most sources — especially Mintlify — is that **
 - **Don't set `deployment.site`.** Blume auto-fills it: the dev server's `localhost` URL in dev, and the deployment URL (`VERCEL_PROJECT_PRODUCTION_URL`/`VERCEL_URL`) on Vercel. Hardcoding it in `blume.config.ts` overrides that auto-detection and pins the wrong absolute URL (canonical links, sitemap, OG, llms.txt) everywhere but the one host you typed — so leave it unset even when a source config had a `url`/`site` field. (Sitemap still generates in production because the deploy URL is present there.)
 - **Favicon is a filename convention, not config.** Drop `icon`/`favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` **collapses to one** — pick a single file and report the loss.
 
-The schema is exported from `blume/schema`; the full field reference is in `node_modules/blume/docs/configuration/`.
+The schema is exported from `blume/schema`; the full field reference is in the `docs/configuration/` directory of the installed `blume` package (see "Full documentation" below for how to locate it).
 
 ### Icons are Lucide, period
 
@@ -160,7 +162,7 @@ A `redirects: [{ from, to, status? }]` array **in `blume.config.ts`** maps old U
 
 ## Full documentation
 
-The mapping details live in `references/`: one file per source framework (`mintlify.md`, `docusaurus.md`, `fumadocs.md`, `nextra.md`, `starlight.md`), plus **`monorepo.md`** for host-repo integration (content-layout detection, pnpm `minimumReleaseAge`, frozen-lockfile regeneration, the Vercel monorepo recipe, and the Astro/Vite patch). The Mintlify icon + frontmatter pass is automated by **`scripts/mintlify-codemod.mjs`** (zero-dependency, deterministic, idempotent; `--write` to apply). The authoritative Blume docs are bundled in the installed package at **`node_modules/blume/docs`** (or `apps/docs/content/docs` in a repo checkout). The most relevant pages:
+The mapping details live in `references/`: one file per source framework (`mintlify.md`, `docusaurus.md`, `fumadocs.md`, `nextra.md`, `starlight.md`), plus **`monorepo.md`** for host-repo integration (content-layout detection, pnpm `minimumReleaseAge`, frozen-lockfile regeneration, the Vercel monorepo recipe, and the Astro/Vite patch). The Mintlify icon + frontmatter pass is automated by **`scripts/mintlify-codemod.mjs`** (zero-dependency, deterministic, idempotent; `--write` to apply). The authoritative Blume docs are bundled in the installed package's **`docs/` directory** — not necessarily at the repository root: in a workspace monorepo (pnpm especially) the package lives in the depending workspace's `node_modules` (e.g. `apps/docs/node_modules/blume/docs`); `node -e "console.log(require.resolve('blume/package.json'))"` run from the depending package prints the exact location. (In a repo checkout of Blume itself, the docs source is `apps/docs/content/docs`.) The most relevant pages:
 
 - `configuration/index.mdx` — every `blume.config.ts` field.
 - `content/navigation.mdx` — the sidebar/tabs/selectors model.

package/skills/blume-migrate/references/mintlify.md

@@ -27,7 +27,7 @@ Resolve `$ref` includes first (Mintlify splits config across files). Map only wh
 | `background.color.{light,dark}` | `theme.background` (`{ light, dark }`) | one field now: `background: { light: …, dark: … }` (a bare string applies to both) |
 | `background.image` | `theme.backgroundImage` (`{ light, dark }`) | same per-mode shape as `background` |
 | `background.decoration` | **drop** | no Blume equivalent |
-| `fonts.family` / `fonts.{heading,body}.family` | `theme.fonts.{display,body}` | only if the family is a curated Google-font slug (kebab-case, e.g. `space-grotesk`); otherwise drop and tell the user to add `@font-face` in `theme.css` |
+| `fonts.family` / `fonts.{heading,body}.family` | `theme.fonts.{display,body}` | a curated slug (kebab-case, e.g. `space-grotesk`) maps directly; any other Google family maps to the object form `{ name: "Family Name" }`; a self-hosted font (`fonts.*.src` URLs) maps to `{ name, variants: [{ src, weight }] }` after downloading the files into the project |
 | `banner` | `banner` (`{ content, dismissible, id, link }`) | **only** those keys — drop `banner.color`/`banner.type` |
 | `styling.latex: true` | **drop the field** — block math `$$…$$` renders in `.mdx` with no config | there is **no** `markdown.math` field; inline `$…$` is **not** supported — convert inline math to `$$…$$` or drop it (report) |
 | `styling.codeblocks.theme` | `markdown.codeBlocks.theme` (`{ light, dark }`) |  |
@@ -50,9 +50,9 @@ Mintlify defaults to **FontAwesome**; Blume is **Lucide-only**. Convert every ic
 **Automate the frontmatter pass — don't hand-edit it.** `scripts/mintlify-codemod.mjs` (in this skill, zero-dependency) remaps every **frontmatter** `icon:` using the table below, drops brand/no-equivalent icons, and — in the same pass — drops/renames unsupported frontmatter keys (see [Frontmatter](#frontmatter)). It's deterministic and idempotent, and reports what it changed per file plus what it couldn't (unknown icons, OpenAPI-stub flags):
 
 ```bash
-# dry run first (report only), then apply:
-node <this-skill>/scripts/mintlify-codemod.mjs <content-dir>
-node <this-skill>/scripts/mintlify-codemod.mjs --write <content-dir>
+# <skill> = this skill's directory (the one containing SKILL.md); dry run first (report only), then apply:
+node <skill>/scripts/mintlify-codemod.mjs <content-dir>
+node <skill>/scripts/mintlify-codemod.mjs --write <content-dir>
 ```
 
 The codemod touches **only frontmatter**. Icons in MDX **body** (`<Icon icon="…">`, `<Card icon="…">`, nav-group icons in `docs.json`) it does not see — convert those by hand using the same table. Common mappings:
@@ -153,4 +153,4 @@ Mintlify serves every top-level dir (e.g. `/images`) at the site root. Blume ser
 - **`footer.socials`** → suggest the `github` config, or a Footer override.
 - **Per-language banners** (`navigation.languages[].banner`) → no equivalent.
 - **Dynamic redirects** (`:slug*`/`:id` params) → can't be static path-to-path; move to host rules (`_redirects`, `vercel.json`).
-- **`<Update>`** changelog components, `iconType`, `background.decoration`, `search.prompt`, `seo.metatags`, non-curated fonts.
+- **`<Update>`** changelog components, `iconType`, `background.decoration`, `search.prompt`, `seo.metatags`.

package/skills/blume-migrate/references/monorepo.md

@@ -193,7 +193,8 @@ If the repo uses (or the user wants to adopt) **[Ultracite](https://www.ultracit
 The fix is a committed **pnpm patch** (`patches/oxfmt@0.55.0.patch`), shipped with this skill at `assets/oxfmt@0.55.0.patch`. Unlike the Astro/Vite patch, this one is a **known, deterministic diff** — copy it in, don't regenerate it:
 
 ```bash
-# 1. Copy the shipped patch into the target repo's patches/ dir (keep the exact filename):
+# 1. Copy the shipped patch into the target repo's patches/ dir (keep the exact filename;
+#    <skill> = this skill's directory, the one containing SKILL.md):
 mkdir -p patches
 cp "<skill>/assets/oxfmt@0.55.0.patch" patches/oxfmt@0.55.0.patch
 ```

package/src/ai/agent-readability.ts

@@ -2,6 +2,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 { buildRssFeeds } from "../deploy/rss.ts";
+import { hasApiCatalog } from "./api-catalog.ts";
 
 /** Token map for the machine-readable content-usage echo. */
 const USAGE_TOKENS: [keyof ContentSignalPolicy, string][] = [
@@ -45,6 +46,26 @@ const askApiUrl = (
     : endpoint;
 };
 
+/** The `.well-known` discovery artifacts the site publishes, if any. */
+const wellKnownArtifacts = (
+  config: BlumeProject["config"],
+  abs: (path: string) => string
+): Record<string, string> => {
+  const artifacts: Record<string, string> = {};
+  if (config.ai.webBotAuth.keys.length > 0) {
+    artifacts.httpMessageSignaturesDirectory = abs(
+      "/.well-known/http-message-signatures-directory"
+    );
+  }
+  if (hasApiCatalog(config)) {
+    artifacts.apiCatalog = abs("/.well-known/api-catalog");
+  }
+  if (config.ai.skills) {
+    artifacts.agentSkills = abs("/.well-known/agent-skills/index.json");
+  }
+  return artifacts;
+};
+
 /**
  * Build `agent-readability.json`: a root manifest that indexes the project's
  * agent-facing surface — llms.txt, the raw-Markdown mirrors, the MCP server,
@@ -70,9 +91,17 @@ export const buildAgentReadability = (
     return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
   };
 
+  // Advertise `Accept: text/markdown` negotiation only where the deployed site
+  // actually honors it — a Vercel server build, whose routing config gets the
+  // rewrite rules (see `deploy/vercel-negotiation.ts`). Static builds and other
+  // adapters serve prerendered pages from a static layer with no request-time
+  // hook, so agents there should fetch the `.md` pattern directly.
+  const negotiates =
+    config.deployment.output === "server" &&
+    config.deployment.adapter === "vercel";
   const artifacts: Record<string, unknown> = {
     markdown: {
-      contentNegotiation: "text/markdown",
+      ...(negotiates ? { contentNegotiation: "text/markdown" } : {}),
       pattern: abs("/{route}.md"),
     },
   };
@@ -89,6 +118,7 @@ export const buildAgentReadability = (
   if (config.ai.ask?.enabled) {
     artifacts.askApi = askApiUrl(config.ai.ask.endpoint, site, abs);
   }
+  Object.assign(artifacts, wellKnownArtifacts(config, abs));
   if (site && config.seo.sitemap) {
     artifacts.sitemap = abs("/sitemap.xml");
   }

package/src/ai/api-catalog.ts

@@ -0,0 +1,81 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import { trimEnd } from "../core/trim.ts";
+import { resolveReferences } from "../openapi/references.ts";
+
+/**
+ * RFC 9727 API catalog: a linkset (RFC 9264) at `/.well-known/api-catalog`
+ * enumerating the APIs a publisher offers, so agents can discover them from
+ * the domain alone. Blume already knows the site's APIs — the configured
+ * OpenAPI/AsyncAPI references and the hosted MCP server — so the catalog is
+ * generated, never hand-written: one entry per API, anchored at its docs
+ * route (the RFC's own examples anchor on developer-portal pages), with
+ * `service-doc` pointing at the rendered reference and `service-desc` at the
+ * spec when it lives at a fetchable URL.
+ */
+
+export const API_CATALOG_PATH = "/.well-known/api-catalog";
+export const API_CATALOG_TYPE = "application/linkset+json";
+
+/** An RFC 9264 linkset entry, restricted to the relations Blume emits. */
+interface LinksetEntry {
+  anchor: string;
+  "service-desc"?: { href: string; type?: string }[];
+  "service-doc"?: { href: string; type: string }[];
+}
+
+const HTTP_URL = /^https?:\/\//u;
+
+/** The catalog's linkset entries; empty when the site publishes no APIs. */
+const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
+  const site = config.deployment.site ?? null;
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const abs = (path: string): string => {
+    const based = withBasePath(deployBase, path);
+    return site ? `${trimEnd(site, "/")}${based}` : based;
+  };
+
+  const entries: LinksetEntry[] = [];
+  for (const reference of resolveReferences(config)) {
+    // Blume-rendered pages mount under `basePath`; Scalar pages stay at the
+    // raw route (see `referenceRoutes`).
+    const docRoute =
+      reference.renderer === "blume"
+        ? withBasePath(reference.basePath, reference.route)
+        : reference.route;
+    const entry: LinksetEntry = {
+      anchor: abs(docRoute),
+      "service-doc": [{ href: abs(docRoute), type: "text/html" }],
+    };
+    // A local spec file is parsed into pages, not served, so only a remote
+    // spec has a fetchable `service-desc` URL.
+    if (HTTP_URL.test(reference.spec)) {
+      entry["service-desc"] = [{ href: reference.spec }];
+    }
+    entries.push(entry);
+  }
+
+  if (config.ai.mcp.enabled) {
+    entries.push({
+      anchor: abs(config.ai.mcp.route),
+      "service-desc": [
+        { href: abs("/.well-known/mcp.json"), type: "application/json" },
+      ],
+      "service-doc": [{ href: abs("/"), type: "text/html" }],
+    });
+  }
+  return entries;
+};
+
+/** Whether the site has anything to catalog — gates every emission surface. */
+export const hasApiCatalog = (config: ResolvedConfig): boolean =>
+  linksetEntries(config).length > 0;
+
+/** The `application/linkset+json` document, or null when there are no APIs. */
+export const buildApiCatalog = (config: ResolvedConfig): string | null => {
+  const linkset = linksetEntries(config);
+  if (linkset.length === 0) {
+    return null;
+  }
+  return `${JSON.stringify({ linkset }, null, 2)}\n`;
+};

package/src/ai/link-headers.ts

@@ -0,0 +1,53 @@
+import { normalizeBasePath } from "../core/base-path.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
+
+/**
+ * The homepage `Link` response header (RFC 8288) — agent discovery for the
+ * machine-readable surface Blume already publishes. Agents probing a site read
+ * this header off `GET /` to find the resources without scraping HTML:
+ * `agent-readability.json` and `llms.txt` as `rel="describedby"`, and the
+ * homepage's raw-Markdown mirror as `rel="alternate"` (only when the home
+ * route is a content page — a user landing page has no mirror). Both rel
+ * values are IANA-registered, which agent-readiness checkers require.
+ *
+ * The header is homepage-only by design: the root response is what agents
+ * probe, and `agent-readability.json` indexes the rest of the surface (the
+ * per-route Markdown pattern, MCP, feeds) far better than per-page headers
+ * could. Targets are root-relative under `deployment.base` — RFC 8288 resolves
+ * them against the request URL. Returns null when nothing is advertisable.
+ */
+export const buildHomeLinkHeader = (
+  config: ResolvedConfig,
+  routePaths: readonly string[]
+): string | null => {
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const links: string[] = [];
+  // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
+  // well-known catalog.
+  if (hasApiCatalog(config)) {
+    links.push(
+      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="application/linkset+json"`
+    );
+  }
+  if (config.seo.agentReadability) {
+    links.push(
+      `<${deployBase}/agent-readability.json>; rel="describedby"; type="application/json"`
+    );
+  }
+  if (config.ai.llmsTxt.enabled) {
+    links.push(
+      `<${deployBase}/llms.txt>; rel="describedby"; type="text/plain"`
+    );
+  }
+  // Same route list as the negotiation surfaces (`markdownRoutePaths`): "/"
+  // always has a mirror — the page's own source when the home route is a
+  // content page, the synthesized llms.txt fallback otherwise — so callers
+  // passing that list always advertise `/index.md` here.
+  if (routePaths.includes("/")) {
+    links.push(
+      `<${deployBase}/index.md>; rel="alternate"; type="text/markdown"`
+    );
+  }
+  return links.length > 0 ? links.join(", ") : null;
+};

package/src/ai/llms.ts

@@ -1,4 +1,5 @@
 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 { readEntryText } from "../core/sources/read.ts";
@@ -59,8 +60,10 @@ const indexedNavigations = (
  * Build the compact `llms.txt` index: title and summary, then the sidebar tree
  * rendered as sections — group labels become headings, pages become link lists —
  * so the file mirrors how the docs are organized rather than one flat blob.
+ * Also serves as the homepage's synthesized Markdown mirror when the home
+ * route is a landing page (see `buildRawMarkdown`).
  */
-const buildIndex = (project: BlumeProject): string => {
+export const buildLlmsIndex = (project: BlumeProject): string => {
   const { config } = project;
   const { site } = config.deployment;
   const base = normalizeBasePath(config.deployment.base);
@@ -180,7 +183,17 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
 
   const sections = await Promise.all(
     pages.map(async (page) => {
-      const raw = await readEntryText(project, page);
+      let raw = await readEntryText(project, page);
+      // Colocated `./image.png` references resolve to nothing for a reader of
+      // llms-full.txt; point them at the served originals instead.
+      if (page.sourcePath) {
+        raw = rewriteRelativeImages({
+          deployBase: config.deployment.base,
+          projectRoot: project.context.root,
+          source: raw,
+          sourcePath: page.sourcePath,
+        });
+      }
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.
@@ -211,5 +224,5 @@ export const buildLlmsFiles = async (
   project: BlumeProject
 ): Promise<{ index: string; full: string }> => ({
   full: await buildFull(project),
-  index: buildIndex(project),
+  index: buildLlmsIndex(project),
 });

package/src/ai/markdown.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
@@ -8,6 +9,7 @@ import {
   downlevelComponents,
   exampleComponentSerializers,
 } from "./component-markdown.ts";
+import { buildLlmsIndex } from "./llms.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -27,13 +29,26 @@ export interface RawMarkdownEntry {
 export const agentMarkdown = (entry: RawMarkdownEntry): string =>
   entry.md ?? entry.mdx;
 
+/**
+ * Estimated token count of a Markdown document, for the `x-markdown-tokens`
+ * response header (the convention Cloudflare's Markdown for Agents ships; the
+ * tokenizer is unspecified there too, so this is the common ~4-characters-
+ * per-token estimate). Kept in sync with the inline computation in
+ * `rawMarkdownEndpointTemplate`, which can't import build-time code.
+ */
+export const markdownTokenCount = (text: string): number =>
+  Math.ceil(text.length / 4);
+
 /**
  * Map every route to its raw source Markdown. Powers the `<route>.md` and
  * `<route>.mdx` endpoints: `.mdx` serves the original source so tools can see
  * exactly what the author wrote, while `.md` downlevels supported components
  * to plain Markdown for consumers that can't interpret JSX. `<Visibility>`
  * audiences are resolved for agents in both variants: web-only content is
- * removed, agents-only unwrapped.
+ * removed, agents-only unwrapped. Relative image references are rewritten to
+ * their served `/blume-assets/content/…` URLs in both variants too — an agent
+ * fetches these endpoints by URL, where a colocated `./diagram.png` resolves
+ * to nothing.
  */
 export const buildRawMarkdown = async (
   project: BlumeProject
@@ -57,7 +72,16 @@ export const buildRawMarkdown = async (
 
   const entries = await Promise.all(
     project.manifest.routes.map(async (route) => {
-      const source = applyAgentVisibility(await readRoute(route));
+      let text = await readRoute(route);
+      if (route.sourcePath) {
+        text = rewriteRelativeImages({
+          deployBase: project.config.deployment.base,
+          projectRoot: project.context.root,
+          source: text,
+          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.
       const md = downlevelComponents(source, components, matter(source).data);
@@ -66,5 +90,27 @@ export const buildRawMarkdown = async (
       return [route.path, entry] as const;
     })
   );
-  return Object.fromEntries(entries);
+  const map = Object.fromEntries(entries);
+  // 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`).
+  if (!map["/"]) {
+    map["/"] = { mdx: buildLlmsIndex(project) };
+  }
+  return map;
+};
+
+/**
+ * Every route path with a raw-Markdown mirror: the manifest routes, plus the
+ * homepage when its mirror is the synthesized llms.txt fallback (see
+ * `buildRawMarkdown`). This is the route list the negotiation surfaces (dev
+ * middleware, Vercel routing config) and the homepage `Link` header build
+ * from, so `Accept: text/markdown` on `/` resolves even when the homepage is
+ * a landing page.
+ */
+export const markdownRoutePaths = (project: BlumeProject): string[] => {
+  const paths = project.manifest.routes.map((route) => route.path);
+  return paths.includes("/") ? paths : [...paths, "/"];
 };

package/src/ai/mcp/discovery.ts

@@ -1,5 +1,6 @@
 import { withBasePath } from "../../core/base-path.ts";
 import { trimEnd } from "../../core/trim.ts";
+import { slugify } from "../../openapi/references.ts";
 import { MCP_TOOLS } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
@@ -38,22 +39,76 @@ export const buildMcpDiscovery = (
   ],
 });
 
+/** The published `/v1/` Server Card schema (SEP-2127 extension). */
+const SERVER_CARD_SCHEMA =
+  "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+
+/** The schema caps `description` (and `title`) at 100 characters. */
+const CARD_TEXT_MAX = 100;
+
+const truncate = (text: string): string =>
+  text.length > CARD_TEXT_MAX ? `${text.slice(0, CARD_TEXT_MAX - 1)}…` : text;
+
 /**
- * The `/.well-known/mcp/server-card.json` document: richer metadata including
- * the advertised tool set (full input schemas are served live via `tools/list`).
+ * 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.
+ */
+const reverseDnsName = (input: McpDiscoveryInput): string => {
+  let namespace = "localhost";
+  if (input.site) {
+    try {
+      namespace = new URL(input.site).hostname
+        .split(".")
+        .toReversed()
+        .join(".");
+    } catch {
+      // Not a parsable URL; the local namespace is honest enough.
+    }
+  }
+  return `${namespace}/${slugify(input.name) || "docs"}`;
+};
+
+const HTTP_URL = /^https?:\/\//u;
+
+/**
+ * The `/.well-known/mcp/server-card.json` document. The core follows the
+ * SEP-2127 Server Card extension schema (`$schema`, reverse-DNS `name`,
+ * `remotes` — which the schema requires to be absolute, so it appears only
+ * when a `site` is configured). Alongside it ride initialize-shaped compat
+ * fields (`serverInfo`, `capabilities`, `transports`) for scanners built
+ * against the SEP's earlier revision, plus Blume's advertised tool set —
+ * schema-legal extras (`additionalProperties` is open), and the tool list is
+ * genuinely static for a docs server, unlike the dynamic servers the spec
+ * excludes primitives for. Full input schemas are served live via
+ * `tools/list`.
  */
 export const buildMcpServerCard = (
   input: McpDiscoveryInput
-): Record<string, unknown> => ({
-  description: `Model Context Protocol server for the ${input.name} documentation.`,
-  name: input.name,
-  tools: MCP_TOOLS.map((tool) => ({
-    annotations: tool.annotations,
-    description: tool.description,
-    name: tool.name,
-    title: tool.title,
-  })),
-  transport: "streamable-http",
-  url: serverUrl(input),
-  version: input.version,
-});
+): Record<string, unknown> => {
+  const url = serverUrl(input);
+  return {
+    $schema: SERVER_CARD_SCHEMA,
+    capabilities: { tools: { listChanged: false } },
+    description: truncate(
+      `Model Context Protocol server for the ${input.name} documentation.`
+    ),
+    name: reverseDnsName(input),
+    ...(HTTP_URL.test(url)
+      ? { remotes: [{ type: "streamable-http", url }] }
+      : {}),
+    serverInfo: { name: input.name, version: input.version },
+    title: truncate(input.name),
+    tools: MCP_TOOLS.map((tool) => ({
+      annotations: tool.annotations,
+      description: tool.description,
+      name: tool.name,
+      title: tool.title,
+    })),
+    transport: "streamable-http",
+    transports: [{ endpoint: url, type: "streamable-http" }],
+    url,
+    version: input.version,
+    ...(input.site ? { websiteUrl: trimEnd(input.site, "/") } : {}),
+  };
+};

package/src/ai/mcp/server.ts

@@ -13,9 +13,10 @@ import { MCP_TOOLS } from "./tools.ts";
 
 /**
  * The low-level SDK `Server` is used (rather than the high-level `McpServer`)
- * because the latter's `registerTool` is generic over the caller's Zod version;
- * Blume pins Zod 3 while the SDK resolves Zod 4, so their types don't unify.
- * Hand-written JSON Schema and the SDK's own request schemas avoid that entirely.
+ * because the latter's `registerTool` is generic over the caller's Zod instance;
+ * Blume's zod and the SDK's may resolve to different copies, whose types don't
+ * unify. Hand-written JSON Schema and the SDK's own request schemas avoid that
+ * entirely.
  */
 
 /** Default and maximum number of hits returned by `search_docs`. */
@@ -149,7 +150,7 @@ export const createIndexProvider = (
   locale?: string
 ): OramaIndexProvider => {
   let dbPromise: ReturnType<OramaIndexProvider> | null = null;
-  return () => {
+  return function provideIndex() {
     dbPromise ??= buildOramaIndex(documents, locale);
     return dbPromise;
   };