blume 1.2.1 → 1.3.0

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,52 @@
+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 home-mirror condition as the Vercel negotiation routes: "/" is a
+  // content route only when the docs sit at the site root (no `basePath`) and
+  // the root page is real content, so `/index.md` exists exactly then.
+  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";
@@ -180,7 +181,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.

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";
@@ -33,7 +34,10 @@ export const agentMarkdown = (entry: RawMarkdownEntry): string =>
  * 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 +61,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);

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;
   };

package/src/ai/skills.ts

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import { normalizeBasePath } from "../core/base-path.ts";
+import matter from "../core/frontmatter.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+import { buildTarGz } from "./tar.ts";
+import type { TarEntry } from "./tar.ts";
+
+/**
+ * Agent Skills discovery (Cloudflare's Agent Skills Discovery RFC v0.2.0):
+ * the skills a site publishes are enumerated in an index at
+ * `/.well-known/agent-skills/index.json`, each entry pointing at its artifact
+ * with a SHA-256 digest. A skill that is only a `SKILL.md` publishes the file
+ * verbatim (`type: "skill-md"`); a skill with supporting resources (scripts,
+ * references, assets) is bundled into a deterministic `.tar.gz`
+ * (`type: "archive"`) so its relative references resolve after unpacking.
+ */
+
+export const AGENT_SKILLS_DIR = "/.well-known/agent-skills";
+export const AGENT_SKILLS_INDEX_PATH = "/.well-known/agent-skills/index.json";
+
+const AGENT_SKILLS_SCHEMA =
+  "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+
+/** Skill naming rule from the Agent Skills spec (1-64 chars enforced apart). */
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const SKILL_NAME_MAX = 64;
+/** The Agent Skills spec caps `description` at 1024 characters. */
+const DESCRIPTION_MAX = 1024;
+
+/** One publishable skill artifact plus its index entry. */
+export interface SkillArtifact {
+  /** Raw bytes to publish (the digest is computed over exactly these). */
+  content: Uint8Array;
+  description: string;
+  /** `sha256:{hex}` digest of `content`. */
+  digest: string;
+  name: string;
+  /** Path under the agent-skills dir: `{name}/SKILL.md` or `{name}.tar.gz`. */
+  path: string;
+  type: "archive" | "skill-md";
+}
+
+export interface CollectedSkills {
+  skills: SkillArtifact[];
+  /** Human-readable reasons for anything skipped. */
+  warnings: string[];
+}
+
+const sha256 = (content: Uint8Array): string =>
+  `sha256:${createHash("sha256").update(content).digest("hex")}`;
+
+/**
+ * Every regular file under a skill directory, as archive entries with
+ * `/`-separated relative paths, dotfiles (`.DS_Store`, `.git`) excluded,
+ * sorted for deterministic archives. The owner-execute bit is preserved so a
+ * skill's scripts stay runnable after unpacking.
+ */
+const collectEntries = async (
+  dir: string,
+  prefix = ""
+): Promise<TarEntry[]> => {
+  const entries: TarEntry[] = [];
+  const items = await readdir(dir, { withFileTypes: true });
+  for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (item.name.startsWith(".")) {
+      continue;
+    }
+    const path = join(dir, item.name);
+    const relative = prefix ? `${prefix}/${item.name}` : item.name;
+    if (item.isDirectory()) {
+      // Sequential recursion keeps ordering deterministic.
+      // oxlint-disable-next-line no-await-in-loop
+      entries.push(...(await collectEntries(path, relative)));
+    } else if (item.isFile()) {
+      // oxlint-disable-next-line no-await-in-loop
+      const [content, info] = await Promise.all([readFile(path), stat(path)]);
+      entries.push({
+        content: new Uint8Array(content),
+        // oxlint-disable-next-line no-bitwise -- testing the owner-execute mode bit
+        executable: (info.mode & 0o100) !== 0,
+        path: relative,
+      });
+    }
+  }
+  return entries;
+};
+
+/** Frontmatter of a SKILL.md, or null with a warning when unusable. */
+const skillMeta = (
+  raw: string,
+  dirName: string
+): { meta: { description: string; name: string } | null; warning?: string } => {
+  let data: Record<string, unknown>;
+  try {
+    ({ data } = matter(raw) as unknown as { data: Record<string, unknown> });
+  } catch {
+    return {
+      meta: null,
+      warning: `Skill "${dirName}" has unparsable SKILL.md frontmatter; skipped.`,
+    };
+  }
+  const name = typeof data.name === "string" ? data.name : "";
+  const description =
+    typeof data.description === "string" ? data.description : "";
+  if (!(name && description)) {
+    return {
+      meta: null,
+      warning: `Skill "${dirName}" is missing the required "name"/"description" frontmatter; skipped.`,
+    };
+  }
+  if (!SKILL_NAME.test(name) || name.length > SKILL_NAME_MAX) {
+    return {
+      meta: null,
+      warning: `Skill "${dirName}" has an invalid name "${name}" (lowercase alphanumerics and single hyphens, max 64 chars); skipped.`,
+    };
+  }
+  return {
+    meta: { description: description.slice(0, DESCRIPTION_MAX), name },
+  };
+};
+
+/**
+ * Collect the publishable skills from a directory whose subdirectories each
+ * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories
+ * without one are ignored silently — the directory may hold other assets —
+ * while a present-but-invalid skill earns a warning so it isn't dropped
+ * behind the publisher's back.
+ */
+export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
+  const skills: SkillArtifact[] = [];
+  const warnings: string[] = [];
+  const items = await readdir(dir, { withFileTypes: true });
+  for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (!item.isDirectory() || item.name.startsWith(".")) {
+      continue;
+    }
+    // oxlint-disable-next-line no-await-in-loop
+    const entries = await collectEntries(join(dir, item.name));
+    const skillMd = entries.find((entry) => entry.path === "SKILL.md");
+    if (!skillMd) {
+      continue;
+    }
+    const { meta, warning } = skillMeta(
+      new TextDecoder().decode(skillMd.content),
+      item.name
+    );
+    if (!meta) {
+      if (warning) {
+        warnings.push(warning);
+      }
+      continue;
+    }
+    // A lone SKILL.md ships verbatim; supporting resources ship as an
+    // archive so the skill's relative references resolve after unpacking.
+    const single = entries.length === 1;
+    const content = single ? skillMd.content : buildTarGz(entries);
+    skills.push({
+      content,
+      description: meta.description,
+      digest: sha256(content),
+      name: meta.name,
+      path: single ? `${meta.name}/SKILL.md` : `${meta.name}.tar.gz`,
+      type: single ? "skill-md" : "archive",
+    });
+  }
+  return { skills, warnings };
+};
+
+/**
+ * The discovery index (v0.2.0 schema). Artifact URLs are path-absolute under
+ * `deployment.base` — the RFC resolves them against the index origin.
+ */
+export const buildSkillsIndex = (
+  skills: readonly SkillArtifact[],
+  config: ResolvedConfig
+): string => {
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const index = {
+    $schema: AGENT_SKILLS_SCHEMA,
+    skills: skills.map((skill) => ({
+      description: skill.description,
+      digest: skill.digest,
+      name: skill.name,
+      type: skill.type,
+      url: `${deployBase}${AGENT_SKILLS_DIR}/${skill.path}`,
+    })),
+  };
+  return `${JSON.stringify(index, null, 2)}\n`;
+};