blume 1.2.0 → 1.3.0

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

package/src/ai/tar.ts

@@ -0,0 +1,104 @@
+import { gzipSync } from "node:zlib";
+
+/**
+ * Minimal, dependency-free `.tar.gz` writer for agent-skill archives (POSIX
+ * ustar). Deterministic by construction — fixed mtime/uid/gid, caller-ordered
+ * entries, and Node's gzip header carries no timestamp — so a skill's archive
+ * digest only changes when its content does.
+ */
+
+/** One regular file to archive. Paths are `/`-separated, relative, no `..`. */
+export interface TarEntry {
+  /** Raw file bytes. */
+  content: Uint8Array;
+  /** Preserve the owner-execute bit (e.g. a skill's scripts). */
+  executable?: boolean;
+  /** Archive-relative path, e.g. `SKILL.md` or `references/FORMS.md`. */
+  path: string;
+}
+
+const BLOCK = 512;
+/** ustar `name` field capacity; skill layouts are shallow, so no `prefix`. */
+const NAME_MAX = 100;
+
+const encoder = new TextEncoder();
+
+/** Write an octal field: zero-padded digits followed by a NUL terminator. */
+const octal = (
+  header: Uint8Array,
+  offset: number,
+  length: number,
+  value: number
+): void => {
+  const text = value.toString(8).padStart(length - 1, "0");
+  header.set(encoder.encode(text), offset);
+  header[offset + length - 1] = 0;
+};
+
+const text = (header: Uint8Array, offset: number, value: string): void => {
+  header.set(encoder.encode(value), offset);
+};
+
+const fileHeader = (entry: TarEntry): Uint8Array => {
+  const header = new Uint8Array(BLOCK);
+  text(header, 0, entry.path);
+  octal(header, 100, 8, entry.executable ? 0o755 : 0o644);
+  // uid and gid: root-owned, fixed for determinism.
+  octal(header, 108, 8, 0);
+  octal(header, 116, 8, 0);
+  octal(header, 124, 12, entry.content.byteLength);
+  // mtime: fixed at the epoch for determinism.
+  octal(header, 136, 12, 0);
+  // typeflag "0": regular file.
+  text(header, 156, "0");
+  text(header, 257, "ustar");
+  header[262] = 0;
+  text(header, 263, "00");
+  // devmajor and devminor.
+  octal(header, 329, 8, 0);
+  octal(header, 337, 8, 0);
+  // Checksum: computed with the checksum field treated as eight spaces, then
+  // written as six octal digits, NUL, space (the historical ustar format).
+  header.fill(0x20, 148, 156);
+  let sum = 0;
+  for (const byte of header) {
+    sum += byte;
+  }
+  text(header, 148, sum.toString(8).padStart(6, "0"));
+  header[154] = 0;
+  header[155] = 0x20;
+  return header;
+};
+
+/**
+ * Build a gzipped ustar archive of the given files, in the given order. Paths
+ * longer than the ustar `name` field or escaping the archive root are the
+ * caller's responsibility to filter — this throws to surface a programming
+ * error rather than emitting a corrupt archive.
+ */
+export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
+  const blocks: Uint8Array[] = [];
+  for (const entry of entries) {
+    if (encoder.encode(entry.path).byteLength > NAME_MAX) {
+      throw new Error(`tar path exceeds ${NAME_MAX} bytes: ${entry.path}`);
+    }
+    if (entry.path.startsWith("/") || entry.path.split("/").includes("..")) {
+      throw new Error(`tar path must be archive-relative: ${entry.path}`);
+    }
+    blocks.push(fileHeader(entry), entry.content);
+    const overhang = entry.content.byteLength % BLOCK;
+    if (overhang > 0) {
+      blocks.push(new Uint8Array(BLOCK - overhang));
+    }
+  }
+  // End-of-archive marker: two zero blocks.
+  blocks.push(new Uint8Array(BLOCK * 2));
+  const total = blocks.reduce((sum, block) => sum + block.byteLength, 0);
+  const tar = new Uint8Array(total);
+  let offset = 0;
+  for (const block of blocks) {
+    tar.set(block, offset);
+    offset += block.byteLength;
+  }
+  return new Uint8Array(gzipSync(tar, { level: 9 }));
+};

package/src/ai/web-bot-auth.ts

@@ -0,0 +1,30 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * Web Bot Auth (IETF `webbotauth` WG): an org that runs agents publishes the
+ * agents' HTTP Message Signature public keys in a JWKS at a well-known path
+ * on its domain; sites receiving the signed requests fetch it to verify them.
+ * Blume publishes the directory from `ai.webBotAuth.keys` — the schema admits
+ * public keys only, so the site can never leak signing credentials.
+ */
+
+/** Well-known path (draft-meunier-http-message-signatures-directory). */
+export const SIGNATURES_DIRECTORY_PATH =
+  "/.well-known/http-message-signatures-directory";
+
+/** The directory's registered media type — extensionless, so static hosts
+ * need an explicit Content-Type rule (see `deploy/headers.ts` and the Vercel
+ * `overrides` injection) to serve anything better than octet-stream. */
+export const SIGNATURES_DIRECTORY_TYPE =
+  "application/http-message-signatures-directory+json";
+
+/** The JWKS document to publish, or null when no keys are configured. */
+export const buildSignaturesDirectory = (
+  config: ResolvedConfig
+): string | null => {
+  const { keys } = config.ai.webBotAuth;
+  if (keys.length === 0) {
+    return null;
+  }
+  return `${JSON.stringify({ keys }, null, 2)}\n`;
+};

package/src/astro/generate.ts

@@ -22,14 +22,17 @@ import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import { analyzeComponentOverrides } from "../core/component-overrides.ts";
+import { collectContentAssets } from "../core/content-assets.ts";
 import type {
   BlumeBanner,
   BlumeData,
   BlumeFavicon,
   BlumeLogo,
 } from "../core/data.ts";
+import { BlumeError } from "../core/diagnostics.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
 import {
@@ -43,6 +46,8 @@ import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Diagnostic, Navigation, ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
+import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
 import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
@@ -74,6 +79,7 @@ import {
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
+  contentAssetsEndpointTemplate,
   contentConfigTemplate,
   envTemplate,
   exampleMapTemplate,
@@ -634,7 +640,10 @@ export const searchProviderWarnings = (
 };
 
 /** Absolute path to the configured `examples.css`, or null when unset. */
-const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
+const examplesCssFile = (
+  root: string,
+  config: ResolvedConfig
+): string | null =>
   config.examples.css ? join(root, config.examples.css) : null;
 
 /**
@@ -1029,6 +1038,55 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   };
 };
 
+/**
+ * The OG card's brand mark: a `seo.og.logo` of `false` opts out of any mark,
+ * a configured SVG wins over the site logo, and a non-SVG value resolves to
+ * `undefined` (the card falls back to the accent-initial tile).
+ */
+const resolveOgMark = (
+  project: BlumeProject,
+  siteLogo: string | undefined
+): string | false | undefined => {
+  const configured = project.config.seo.og.logo;
+  if (configured === false) {
+    return false;
+  }
+  if (configured) {
+    return resolveOgLogo(project, configured);
+  }
+  return siteLogo;
+};
+
+/**
+ * The OG card's footer site text. A `seo.og.site` override wins (`false`
+ * hides it); the default is the deployment site's host plus the normalized
+ * deployment base — on a subpath deploy (a GitHub Pages project site) the
+ * bare host is the platform's shared apex, not this site (#139).
+ */
+const resolveOgSite = (config: ResolvedConfig): string | undefined => {
+  const configured = config.seo.og.site;
+  if (configured === false) {
+    return;
+  }
+  if (configured !== undefined) {
+    return configured;
+  }
+  return config.deployment.site
+    ? `${new URL(config.deployment.site).host}${normalizeBasePath(
+        config.deployment.base
+      )}`
+    : undefined;
+};
+
+/** The OG card's subtitle: `seo.og.description` (`false` omits it) over the site description. */
+const resolveOgDescription = (config: ResolvedConfig): string | undefined => {
+  const configured = config.seo.og.description;
+  if (configured === false) {
+    return;
+  }
+  return configured ?? config.description;
+};
+
 /** Serialize the content graph into the data module the runtime consumes. */
 export const buildRuntimeData = (project: BlumeProject): string => {
   const { config, context, graph, manifest } = project;
@@ -1038,9 +1096,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     : null;
   const editBase = github ? `${repoUrl}/edit/${github.branch}` : null;
   const logo = resolveLogo(project);
-  const ogLogo = config.seo.og.logo
-    ? resolveOgLogo(project, config.seo.og.logo)
-    : logo?.svg;
+  const ogLogo = resolveOgMark(project, logo?.svg);
 
   const editUrlFor = (sourcePath?: string): string | null => {
     if (!(editBase && sourcePath)) {
@@ -1139,11 +1195,15 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         : null,
       // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
       // the optional schema type so the serialized shape stays `boolean`.
+      // Card fonts are baked into the generated OG endpoint (they can carry
+      // absolute build-machine paths), not serialized here — this snapshot
+      // ends up in every page's client data.
       og: {
+        description: resolveOgDescription(config),
         enabled: config.seo.og.enabled ?? false,
-        fonts: config.seo.og.fonts ?? [],
         logo: ogLogo,
         palette: config.seo.og.palette,
+        site: resolveOgSite(config),
       },
       repoUrl,
       search: {
@@ -1156,6 +1216,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      webmcp: {
+        enabled: config.ai.webmcp,
+        llms: config.ai.llmsTxt.enabled,
+      },
       x: config.seo.x,
     },
     feeds: buildRssFeeds(project).map((feed) => ({
@@ -1393,6 +1457,37 @@ const contentWatchesRuntimeDir = (
   hasFilesystemSource &&
   runtimeDirWithin(collectionBase, context.outDir) !== null;
 
+/** The OG endpoint fonts for a scanned project (see {@link resolveOgFonts}). */
+const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
+  resolveOgFonts(
+    {
+      ogFonts: project.config.seo.og.fonts,
+      themeFonts: project.config.theme.fonts,
+      themeFontsConfigured: project.themeFontsConfigured,
+    },
+    project.context.root
+  );
+
+/**
+ * Fail generation when a configured local font file is missing. Warning and
+ * continuing is not an option here — the path is emitted into the Astro
+ * config and the OG endpoint, which would crash later with a bare ENOENT.
+ */
+const assertFontFilesExist = (project: BlumeProject): void => {
+  const { config, context } = project;
+  const missing = missingFontFiles(
+    { ogFonts: config.seo.og.fonts ?? [], themeFonts: config.theme.fonts },
+    context.root
+  );
+  if (missing.length > 0) {
+    throw new BlumeError({
+      code: "BLUME_FONT_FILE_MISSING",
+      message: `Configured font file(s) not found: ${missing.join(", ")}. Font paths resolve relative to the project root.`,
+      severity: "error",
+    });
+  }
+};
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -1401,6 +1496,7 @@ export const generateRuntime = async (
   project: BlumeProject
 ): Promise<GenerateResult> => {
   const { context, config } = project;
+  assertFontFilesExist(project);
   const out = context.outDir;
   const srcDir = join(out, "src");
   const askPath = join(srcDir, "generated", "Ask.astro");
@@ -1642,7 +1738,7 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes)
+      ogEndpointTemplate(ogRoutes, projectOgFonts(project))
     );
   }
 
@@ -1699,6 +1795,10 @@ export const generateRuntime = async (
   }
 
   const rawMarkdown = await buildRawMarkdown(project);
+  // The originals behind the rewritten `/blume-assets/content/…` references in
+  // the agent-facing Markdown, plus the endpoint that serves them (and the
+  // remote-source assets materialized under `.blume/public/blume-assets`).
+  const contentAssets = await collectContentAssets(project);
   await Promise.all([
     write(
       join(srcDir, "generated", "raw-markdown.json"),
@@ -1712,6 +1812,16 @@ export const generateRuntime = async (
       join(srcDir, "pages", "[...slug].mdx.ts"),
       rawMarkdownEndpointTemplate("mdx")
     ),
+    write(
+      join(srcDir, "generated", "content-assets.json"),
+      `${JSON.stringify(contentAssets)}\n`
+    ),
+    write(
+      join(srcDir, "pages", "blume-assets", "[...asset].ts"),
+      contentAssetsEndpointTemplate(
+        join(project.context.outDir, "public", "blume-assets")
+      )
+    ),
   ]);
 
   // Automatic RSS feeds for blog/changelog content types (a no-op when no such

package/src/astro/integration.ts

@@ -78,27 +78,61 @@ export interface BlumeIntegrationOptions {
   contentRoutes: string[];
   /** Configured `deployment.base`, stripped from dev URLs before matching. */
   base?: string;
+  /**
+   * Homepage `Link` header value for agent discovery (see
+   * `ai/link-headers.ts`); the dev-server counterpart of the `_headers` /
+   * Vercel-config emission, so `curl -I` against `blume dev` shows what the
+   * deployed site will send.
+   */
+  homeLinkHeader?: string;
 }
 
+/**
+ * Whether a dev-server request URL is the homepage: the path (query dropped,
+ * `deployment.base` stripped, trailing slash tolerated) is the root.
+ */
+const isHomeUrl = (rawUrl: string | undefined, base?: string): boolean => {
+  if (!rawUrl) {
+    return false;
+  }
+  const queryIndex = rawUrl.indexOf("?");
+  let path = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+  const prefix = base && base !== "/" ? base.replace(/\/$/u, "") : "";
+  if (prefix) {
+    if (path !== prefix && !path.startsWith(`${prefix}/`)) {
+      return false;
+    }
+    path = path.slice(prefix.length);
+  }
+  return path === "" || path === "/";
+};
+
 /**
  * Dev-server content negotiation: when a client asks for `text/markdown`,
  * transparently rewrite a content-page request to its `.md` variant so the
- * existing raw-Markdown endpoint serves it. Runs only under `blume dev`; static
- * and server builds expose the same content at the `.md` URL. Only routes with
- * a Markdown variant are rewritten, so landing pages and user `.astro` pages
- * keep serving HTML.
+ * existing raw-Markdown endpoint serves it. Runs only under `blume dev` — in
+ * production the content pages are prerendered and served from the platform's
+ * static layer, which this middleware never fronts. Vercel server builds get
+ * the same negotiation from routing rules spliced into the Build Output config
+ * (see `deploy/vercel-negotiation.ts`); every other build exposes the same
+ * content at the `.md` URL. Only routes with a Markdown variant are rewritten,
+ * so landing pages and user `.astro` pages keep serving HTML. The same
+ * middleware also stamps the homepage agent-discovery `Link` header, mirroring
+ * what the deployed site sends via `_headers` / the Vercel routing config.
  */
 const negotiateMarkdown =
-  (routes: ReadonlySet<string>, base?: string) =>
+  (routes: ReadonlySet<string>, base?: string, homeLinkHeader?: string) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
-    if (
-      (req.method === "GET" || req.method === "HEAD") &&
-      prefersMarkdown(req.headers.accept)
-    ) {
-      const variant = markdownVariantUrl(req.url, routes, base);
-      if (variant) {
-        res.setHeader("Vary", "Accept");
-        req.url = variant;
+    if (req.method === "GET" || req.method === "HEAD") {
+      if (homeLinkHeader && isHomeUrl(req.url, base)) {
+        res.setHeader("Link", homeLinkHeader);
+      }
+      if (prefersMarkdown(req.headers.accept)) {
+        const variant = markdownVariantUrl(req.url, routes, base);
+        if (variant) {
+          res.setHeader("Vary", "Accept");
+          req.url = variant;
+        }
       }
     }
     next();
@@ -130,7 +164,11 @@ export const blumeIntegration = (
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({
-        handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
+        handle: negotiateMarkdown(
+          new Set(options.contentRoutes),
+          options.base,
+          options.homeLinkHeader
+        ),
         route: "",
       });
     },