blume 2.0.0 → 2.0.2

package/src/astro/templates.ts

@@ -14,7 +14,7 @@ import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { deployPassthrough } from "../deploy/adapters/types.ts";
-import { SVG_ASSET_POLICY } from "../deploy/headers.ts";
+import { SVG_ASSET_HEADERS } from "../deploy/headers.ts";
 import { deployPlatform } from "../deploy/platforms/index.ts";
 import { adapterRoot, distDir } from "../deploy/platforms/paths.ts";
 import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
@@ -196,10 +196,10 @@ export const runtimeDependencies = (options: {
       }
     }
   }
-  // Ask AI's provider SDK, as its adapter declares it (the gateway needs
+  // The assistant's provider SDK, as its adapter declares it (the gateway needs
   // nothing beyond core `ai`, so it declares none).
-  if (config.ai.ask?.enabled && !config.ai.ask.endpoint) {
-    deps.push(...config.ai.ask.provider.runtimeDeps);
+  if (config.ai.assistant?.enabled && !config.ai.assistant.endpoint) {
+    deps.push(...config.ai.assistant.provider.runtimeDeps);
   }
   // The deployment adapter's `@astrojs/*` package, for a server build; the
   // descriptor declares it (and nothing for a static build).
@@ -727,7 +727,7 @@ export const astroConfigTemplate = (options: {
     hasFonts: fontEntries.length > 0,
   });
 
-  // Framework renderers are only wired in when an island (or Ask AI, for React)
+  // Framework renderers are only wired in when an island (or the assistant, for React)
   // needs them. The core theme is Astro-first and ships no client JS.
   const reactImport = needsReact ? `import react from "@astrojs/react";\n` : "";
   const vueImport = needsVue ? `import vue from "@astrojs/vue";\n` : "";
@@ -1064,17 +1064,17 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 const ASK_FALLBACK_PROMPT =
   "You are a helpful documentation assistant. Answer using the project's documentation.";
 
-/** The `ai.ask` values the generated endpoint has to carry with it. */
+/** The `ai.assistant` values the generated endpoint has to carry with it. */
 export interface AskEndpointOptions {
-  /** `ai.ask.cors` — origins allowed to call the route from another site. */
+  /** `ai.assistant.cors` — origins allowed to call the route from another site. */
   cors?: string[];
-  /** `ai.ask.instructions` — extra system-prompt text. */
+  /** `ai.assistant.instructions` — extra system-prompt text. */
   instructions?: string;
-  /** `ai.ask.retrieval` — how much documentation each question carries. */
+  /** `ai.assistant.retrieval` — how much documentation each question carries. */
   retrieval?: AskRetrievalOptions;
 }
 
-/** The pieces `askEndpointTemplate` splices in for `ai.ask.cors`. */
+/** The pieces `askEndpointTemplate` splices in for `ai.assistant.cors`. */
 interface AskCorsTemplate {
   /** The route's closing token: `});` when the POST is wrapped, `};` otherwise. */
   close: string;
@@ -1087,7 +1087,7 @@ interface AskCorsTemplate {
 }
 
 /**
- * `ai.ask.cors`: a browser only lets another origin read the stream when the
+ * `ai.assistant.cors`: a browser only lets another origin read the stream when the
  * response names that origin, and a JSON POST preflights first, so the route
  * answers `OPTIONS` and wraps the `POST` in `withCors`, which stamps a listed
  * origin on every response — errors included, so a cross-origin caller can
@@ -1114,14 +1114,14 @@ export const OPTIONS: APIRoute = ({ request }) =>
     : { close: "};", imports: [], open: "async ({ request }) => {", setup: "" };
 
 /**
- * Largest request body the Ask AI route reads: 64 KB, well above the
+ * Largest request body the assistant route reads: 64 KB, well above the
  * 24,000-character message budget it validates next, so a real conversation
  * never meets it.
  */
 const ASK_BODY_LIMIT_BYTES = 65_536;
 
 /**
- * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
+ * Generate the assistant server endpoint (`.blume/src/pages/api/ask.ts`).
  *
  * The provider-specific pieces — imports, the provider factory call, the model
  * expression, the credential guard, and the adapter's reasoning mapping and
@@ -1130,11 +1130,11 @@ const ASK_BODY_LIMIT_BYTES = 65_536;
  * `blume.config.ts`. `backend.grounded` decides whether answers are grounded
  * in the retrieved docs (every adapter but Inkeep, which retrieves itself).
  *
- * `options.instructions` (the `ai.ask.instructions` config) is appended to the
+ * `options.instructions` (the `ai.assistant.instructions` config) is appended to the
  * built-in prompt on every path: the grounded prompt via `createAskContext`,
- * and the plain fallback here. `options.retrieval` (the `ai.ask.retrieval`
+ * and the plain fallback here. `options.retrieval` (the `ai.assistant.retrieval`
  * config) is forwarded to `createAskContext` on the grounded path, where it
- * sizes retrieval. `options.cors` (the `ai.ask.cors` config) adds a preflight
+ * sizes retrieval. `options.cors` (the `ai.assistant.cors` config) adds a preflight
  * handler and wraps the `POST` so every response names a listed origin. All
  * three travel in one options object so a new call site can't silently drop
  * one of them.
@@ -1232,7 +1232,7 @@ export const askEndpointTemplate = (
   // Provider errors surface mid-stream, after the 200 is committed; this is
   // the only place they can be observed server-side.
   const onError = `      onError({ error }) {
-        console.error("Ask AI provider error:", error);
+        console.error("Assistant provider error:", error);
       },`;
   // The `streamText` argument list, built once so the grounded and plain
   // paths can't drift: they differ only in where the instructions come from.
@@ -1281,9 +1281,9 @@ ${handler}
  * Generate `.blume/src/generated/Ask.astro` — the component behind the
  * `blume:ask` alias that the shared header renders in place of a per-page slot.
  *
- * The header can't import the Ask AI island directly: it's a React component, so
+ * The header can't import the assistant island directly: it's a React component, so
  * the import alone would drag the JSX renderer into the module graph of every
- * project — including the ones that never enable Ask AI and therefore have no
+ * project — including the ones that never enable the assistant and therefore have no
  * React integration wired into their generated Astro config (see `needsReact`).
  * Routing the import through a generated component keeps that dependency behind
  * the config switch: enabled projects get the island, disabled ones get a
@@ -1293,25 +1293,25 @@ ${handler}
  * state suggestions are read straight from the data snapshot, which is why no
  * page has to pass them.
  */
-export const askComponentTemplate = (askEnabled: boolean): string =>
-  askEnabled
+export const askComponentTemplate = (assistantEnabled: boolean): string =>
+  assistantEnabled
     ? `---
 // Generated by Blume. Do not edit.
-import AskAI from "blume/components/islands/AskAI.astro";
+import Assistant from "blume/components/islands/Assistant.astro";
 import data from "blume:data";
 
 const { strings } = Astro.props;
 ---
 
-<AskAI
-  endpoint={data.config.ask?.endpoint ?? undefined}
-  strings={strings ?? data.ui.ask}
-  suggestions={data.config.ask?.suggestions ?? []}
+<Assistant
+  endpoint={data.config.assistant?.endpoint ?? undefined}
+  strings={strings ?? data.ui.assistant}
+  suggestions={data.config.assistant?.suggestions ?? []}
 />
 `
     : `---
 // Generated by Blume. Do not edit.
-// Ask AI is off (\`ai.ask.enabled\`), so the header's Ask trigger renders nothing.
+// The assistant is off (\`ai.assistant.enabled\`), so the header's Ask trigger renders nothing.
 // Deliberately imports no React island, keeping the JSX renderer out of projects
 // that don't need it.
 ---
@@ -1377,7 +1377,10 @@ export const createSearch = () => create(${JSON.stringify(provider.options)});
  * site uses the feature and `null` otherwise, so an unused library is absent
  * from the module graph (never bundled, never pre-bundled in dev) rather than
  * merely lazy. Regenerated on every pass: a page that gains a mermaid fence
- * turns the loader on.
+ * turns the loader on. The EPUB module is named — even in a type — only when
+ * `export.epub` is on: an ejected app depends on `epub-gen-memory` only then,
+ * and a type import of a package it can't resolve fails its type check under
+ * a strict linker such as pnpm.
  */
 export const featuresTemplate = (features: ClientFeatures): string =>
   `// Generated by Blume. Do not edit.
@@ -1394,9 +1397,13 @@ export const loadMermaid: (() => Promise<unknown>) | null = ${
   };
 
 /** The EPUB generator's browser bundle; null when export.epub is off. */
-export const loadEpub:
+${
+  features.epub
+    ? `export const loadEpub:
   | (() => Promise<typeof import("epub-gen-memory/bundle")>)
-  | null = ${features.epub ? '() => import("epub-gen-memory/bundle")' : "null"};
+  | null = () => import("epub-gen-memory/bundle");`
+    : "export const loadEpub: (() => Promise<unknown>) | null = null;"
+}
 `;
 
 /**
@@ -1561,12 +1568,13 @@ export function GET({ props }: { props: { route: string } }) {
  *     materializes under `.blume/public/blume-assets` (see
  *     `core/sources/assets.ts`). That directory is NOT Astro's `publicDir`
  *     (which points at the user project's `public/`), so without this endpoint
- *     those references 404.
+ *     those references 404. `null` for an ejected app, which copies those
+ *     files into its own `public/blume-assets` instead.
  * Prerendered: every asset becomes a static file in the build output; the dev
  * server renders on demand, so new images appear without a restart.
  */
 export const contentAssetsEndpointTemplate = (
-  stagedAssetsDir: string
+  stagedAssetsDir: string | null
 ): string =>
   `// Generated by Blume. Do not edit.
 import { existsSync } from "node:fs";
@@ -1588,18 +1596,29 @@ const TYPES: Record<string, string> = {
   ".ico": "image/x-icon",
   ".jpeg": "image/jpeg",
   ".jpg": "image/jpeg",
+  ".mov": "video/quicktime",
+  ".mp4": "video/mp4",
+  ".ogv": "video/ogg",
   ".png": "image/png",
   ".svg": "image/svg+xml",
   ".tiff": "image/tiff",
+  ".webm": "video/webm",
   ".webp": "image/webp",
 };
 
+const extensionOf = (path: string): string =>
+  path.slice(path.lastIndexOf(".")).toLowerCase();
+
 const contentType = (path: string): string =>
-  TYPES[path.slice(path.lastIndexOf(".")).toLowerCase()] ??
-  "application/octet-stream";
+  TYPES[extensionOf(path)] ?? "application/octet-stream";
+
+// A source downloads only images and videos; anything else in the staged
+// directory (a page an older build saved under its URL's extension) is never
+// published from the docs origin.
+const isMedia = (path: string): boolean => Object.hasOwn(TYPES, extensionOf(path));
 
 const stagedParams = async (): Promise<string[]> => {
-  if (!existsSync(STAGED_DIR)) {
+  if (STAGED_DIR === null || !existsSync(STAGED_DIR)) {
     return [];
   }
   const entries = await readdir(STAGED_DIR, {
@@ -1607,7 +1626,7 @@ const stagedParams = async (): Promise<string[]> => {
     withFileTypes: true,
   });
   return entries
-    .filter((entry) => entry.isFile())
+    .filter((entry) => entry.isFile() && isMedia(entry.name))
     .map((entry) =>
       relative(STAGED_DIR, join(entry.parentPath, entry.name)).replaceAll(
         "\\\\",
@@ -1628,6 +1647,9 @@ const resolveAsset = (asset: string): string | null => {
   if (asset.startsWith("content/")) {
     return files[asset.slice("content/".length)] ?? null;
   }
+  if (STAGED_DIR === null) {
+    return null;
+  }
   const abs = resolve(STAGED_DIR, asset);
   // Traversal guard: the dev server renders on demand, so the param is
   // attacker-controlled there — never step outside the staged directory.
@@ -1637,7 +1659,7 @@ const resolveAsset = (asset: string): string | null => {
   // asset — and a bare prefix also admits a sibling directory that merely
   // shares the name.
   const rel = relative(STAGED_DIR, abs);
-  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel) || !isMedia(rel)) {
     return null;
   }
   return existsSync(abs) ? abs : null;
@@ -1651,11 +1673,12 @@ export const GET: APIRoute = async ({ params }) => {
   const body = await readFile(path);
   const type = contentType(path);
   // An SVG opened directly is a document that can run script; the sandbox
-  // keeps an uploaded one inert on the docs origin. Static hosts get the same
-  // header from the build's header rules.
+  // keeps an uploaded one inert on the docs origin. This endpoint
+  // prerenders, so these headers reach dev only: a build serves the files
+  // with the same headers from its host's rules (see deploy/headers.ts).
   const headers: Record<string, string> =
     type === "image/svg+xml"
-      ? { "Content-Security-Policy": ${JSON.stringify(SVG_ASSET_POLICY)}, "Content-Type": type }
+      ? { ...${JSON.stringify(SVG_ASSET_HEADERS)}, "Content-Type": type }
       : { "Content-Type": type };
   return new Response(new Uint8Array(body), { headers });
 };
@@ -2758,6 +2781,7 @@ export const notFoundPageTemplate = (): string => `---
 import Icon from "blume/components/Icon.astro";
 import PageLayout from "blume/components/layout/PageLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
+import { withBasePath } from "blume/core/base-path.ts";
 import data from "blume:data";
 
 export const prerender = true;
@@ -2795,8 +2819,13 @@ const suggestions = [
 // Every host serves this one page for any missing URL, so a reader who
 // mistyped \`/ar/…\` would get the default locale's message. The other locales'
 // copy rides along, and the script below swaps it in when the URL's first
-// segment names one of them — the message, its language and direction, the
-// tab title, and the home link (to that locale's root).
+// segment past the site's base names one of them — the message, its language
+// and direction, the tab title, and the home link (to that locale's root).
+// Localized routes sit under both bases (\`{deployment.base}/{basePath}/ar/…\`),
+// so the script strips the two together, trailing slash included.
+const { basePath } = data.config;
+const siteRoot = withBase(withBasePath(basePath, "/"));
+const localeBase = siteRoot.endsWith("/") ? siteRoot : siteRoot + "/";
 const localized = Object.fromEntries(
   (i18n?.locales ?? [])
     .filter((l) => l.code !== i18n?.defaultLocale && data.uiByLocale[l.code])
@@ -2808,7 +2837,7 @@ const localized = Object.fromEntries(
           description: strings.description,
           dir: l.dir ?? "ltr",
           home: strings.home,
-          homeHref: withBase("/" + l.code),
+          homeHref: withBase(withBasePath(basePath, "/" + l.code)),
           suggestions: strings.suggestions,
           title: strings.title,
         },
@@ -2837,7 +2866,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
 >
   <div
     class="mx-auto grid w-full max-w-5xl gap-12 px-6 py-20 sm:py-28 md:grid-cols-[3fr_2fr] md:gap-16 lg:gap-24 lg:py-36"
-    data-base={withBase("/")}
+    data-base={localeBase}
     data-blume-not-found
   >
     <div class="flex flex-col items-start">
@@ -3300,11 +3329,20 @@ const Example = entry.Component;
           root.dataset.theme = theme;
           root.classList.toggle("dark", theme === "dark");
         };
-        const stored = () =>
-          localStorage.getItem("blume-theme") ??
-          (matchMedia("(prefers-color-scheme: dark)").matches
-            ? "dark"
-            : "light");
+        // Blocked storage (a sandboxed or privacy-locked frame) throws on
+        // access; it falls through to the OS setting like an unset preference.
+        const stored = () => {
+          let theme = null;
+          try {
+            theme = localStorage.getItem("blume-theme");
+          } catch {}
+          return (
+            theme ??
+            (matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light")
+          );
+        };
         try {
           const host = window.parent.document.documentElement;
           apply(host.dataset.theme ?? stored());

package/src/audit/catalog.ts

@@ -583,7 +583,7 @@ export const CHECKS = [
   },
   {
     category: "sitemap",
-    fix: "Sitemaps must be valid XML in the sitemaps.org urlset format.",
+    fix: "Sitemaps must be valid XML in the sitemaps.org urlset or sitemap index format.",
     id: "BLUME_AUDIT_SITEMAP_INVALID",
     severity: "error",
     tier: "static",
@@ -684,7 +684,7 @@ export const CHECKS = [
   },
   {
     category: "ai",
-    fix: "Rebuild so llms.txt matches the site; if the page is deliberately excluded, mark it `seo.noindex` or `sidebar.hidden`.",
+    fix: "Rebuild so llms.txt matches the site; if the page is deliberately excluded, set `ai.exclude: true` in its front matter.",
     id: "BLUME_AUDIT_LLMS_TXT_PAGE_MISSING",
     severity: "warning",
     tier: "static",

package/src/audit/checks/assets.ts

@@ -11,6 +11,13 @@ import type {
 } from "../types.ts";
 import { resolveHref, siteOrigin } from "../url.ts";
 
+/**
+ * Vercel's image optimization route (`/_vercel/image?url=…&w=…`), which
+ * `imageService` on the Vercel adapter points `<img>` at. The platform
+ * serves it; the build never writes a file there.
+ */
+const VERCEL_IMAGE_ENDPOINT = "/_vercel/image";
+
 const formatBytes = (bytes: number): string =>
   bytes < 1024 * 1024
     ? `${Math.round(bytes / 1024)} kB`
@@ -44,17 +51,30 @@ const resolveAsset = (
   }
 
   const origin = siteOrigin(context.project.config.deployment.options.site);
-  const resolved = resolveHref(
-    page.url,
-    asset.src,
-    origin,
-    normalizeBasePath(context.project.config.deployment.options.base)
+  const deployBase = normalizeBasePath(
+    context.project.config.deployment.options.base
   );
+  const resolved = resolveHref(page.url, asset.src, origin, deployBase);
   // A subresource on another origin (a CDN, an analytics script) is outside the
   // build; we can't check whether it exists without the network.
   if (resolved.kind === "external" || resolved.kind === "ignored") {
     return null;
   }
+  // Vercel's image optimization endpoint answers these at request time, at the
+  // host root whatever the base.
+  if (resolved.path === VERCEL_IMAGE_ENDPOINT) {
+    return null;
+  }
+  if (resolved.kind === "outside-base") {
+    found.push(
+      finding(
+        missingId,
+        pageSite(context, page),
+        `Page references ${asset.src}, which is missing deployment.base (${deployBase}), so the deployed site does not serve it.`
+      )
+    );
+    return null;
+  }
 
   const bytes = context.files.get(resolved.path);
   if (bytes === undefined) {

package/src/audit/checks/content.ts

@@ -38,6 +38,22 @@ const frontmatterDate = (source: string): Date | null => {
   }
 };
 
+/**
+ * API reference pages (OpenAPI, AsyncAPI, GraphQL) are generated from a spec
+ * and have no front matter to edit: their title comes from the operation's
+ * summary (the spec's own title on the overview page) and their description
+ * from its description or summary. A fix naming front matter would send the
+ * reader to a file that doesn't exist.
+ */
+const isGeneratedReference = (page: PageSnapshot): boolean =>
+  page.route?.source.name === "openapi";
+
+const GENERATED_TITLE_FIX =
+  "This page is generated from an API spec, which titles it with the operation's `summary` (the spec's own title on the overview page) — rewrite it there.";
+
+const GENERATED_DESCRIPTION_FIX =
+  "This page is generated from an API spec, which describes it with the operation's `description` or `summary` (the spec's own description on the overview page) — rewrite it there.";
+
 const titleChecks = (
   context: AuditContext,
   page: PageSnapshot
@@ -74,7 +90,8 @@ const titleChecks = (
       finding(
         "BLUME_AUDIT_TITLE_LENGTH",
         pageSite(context, page, ["title"]),
-        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`
+        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`,
+        isGeneratedReference(page) ? GENERATED_TITLE_FIX : undefined
       )
     );
   }
@@ -123,7 +140,8 @@ const descriptionChecks = (
       finding(
         "BLUME_AUDIT_DESCRIPTION_LENGTH",
         pageSite(context, page, ["description"]),
-        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
+        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`,
+        isGeneratedReference(page) ? GENERATED_DESCRIPTION_FIX : undefined
       )
     );
   }

package/src/audit/checks/i18n.ts

@@ -3,7 +3,8 @@ import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
-import { normalizePath } from "../url.ts";
+import { decodePath, normalizePath } from "../url.ts";
+import { isArchivedLatestCanonical } from "./indexability.ts";
 
 /** The normalized `deployment.base` — hreflang hrefs carry it, page URLs don't. */
 const deployBaseOf = (context: AuditContext): string =>
@@ -21,15 +22,52 @@ const isValidBcp47 = (tag: string): boolean => {
   }
 };
 
-/** The site path an hreflang `href` points at, or null when it isn't parseable. */
+/**
+ * The site path an hreflang `href` points at, or null when it isn't parseable.
+ * Percent-decoded like every other URL the audit compares, since page URLs
+ * come from raw on-disk names (`/ガイド`) and `URL#pathname` is encoded.
+ */
 const alternatePath = (href: string, deployBase: string): string | null => {
   try {
-    return normalizePath(stripBasePath(deployBase, new URL(href).pathname));
+    return normalizePath(
+      stripBasePath(deployBase, decodePath(new URL(href).pathname))
+    );
   } catch {
     return null;
   }
 };
 
+/**
+ * An i18n fallback copy renders another locale's page at this locale's URL.
+ * Blume gives it hreflang links to the real translations, which by design
+ * never link back to it (it isn't one), and leaves it out of the sitemap —
+ * so the hreflang cluster checks don't apply to it.
+ */
+const isFallbackCopy = (page: PageSnapshot): boolean =>
+  page.route?.fallback === true;
+
+/**
+ * Whether `target` names a URL other than its own as canonical — unless that
+ * is Blume's archived-version default pointing at the latest equivalent,
+ * which the canonical checks already accept.
+ */
+const canonicalizesElsewhere = (
+  context: AuditContext,
+  target: PageSnapshot,
+  deployBase: string
+): boolean => {
+  if (!target.canonical) {
+    return false;
+  }
+  const canonical = alternatePath(target.canonical, deployBase);
+  if (canonical === normalizePath(target.url)) {
+    return false;
+  }
+  return !(
+    canonical !== null && isArchivedLatestCanonical(context, target, canonical)
+  );
+};
+
 const langChecks = (
   context: AuditContext,
   page: PageSnapshot
@@ -115,10 +153,7 @@ const hreflangChecks = (
           `hreflang="${alternate.lang}" points at ${path}, which the build does not serve.`
         )
       );
-    } else if (
-      target.canonical &&
-      alternatePath(target.canonical, deployBase) !== normalizePath(target.url)
-    ) {
+    } else if (canonicalizesElsewhere(context, target, deployBase)) {
       found.push(
         finding(
           "BLUME_AUDIT_HREFLANG_BAD_TARGET",
@@ -190,6 +225,9 @@ const returnTagChecks = (context: AuditContext): Diagnostic[] => {
   const found: Diagnostic[] = [];
   const deployBase = deployBaseOf(context);
   for (const page of context.pages) {
+    if (isFallbackCopy(page)) {
+      continue;
+    }
     for (const alternate of page.hreflang) {
       if (alternate.lang === X_DEFAULT) {
         continue;
@@ -235,7 +273,7 @@ export const i18nChecks: CheckModule = {
     const found: Diagnostic[] = [];
     for (const page of context.pages) {
       found.push(...langChecks(context, page));
-      if (page.hreflang.length > 0) {
+      if (page.hreflang.length > 0 && !isFallbackCopy(page)) {
         found.push(...hreflangChecks(context, page));
       }
     }

package/src/audit/checks/indexability.ts

@@ -16,6 +16,33 @@ const parseCanonical = (canonical: string): URL | null => {
   }
 };
 
+/**
+ * Whether `page` naming `target` as its canonical is Blume's own default for
+ * an archived-version page (`versions.archived[].canonical: "latest"`)
+ * pointing at its latest equivalent — the live page is the authoritative one
+ * by design, not a defect. `target` is a base-less, normalized site path.
+ */
+export const isArchivedLatestCanonical = (
+  context: AuditContext,
+  page: PageSnapshot,
+  target: string
+): boolean => {
+  const version = page.route?.version;
+  const archived = version
+    ? context.project.config.versions?.archived.find(
+        (entry) => entry.id === version
+      )
+    : undefined;
+  const latestAlternate = page.route?.versionAlternates.find(
+    (alternate) => alternate.version === ""
+  );
+  return (
+    archived?.canonical === "latest" &&
+    latestAlternate !== undefined &&
+    normalizePath(latestAlternate.path) === target
+  );
+};
+
 const canonicalChecks = (
   context: AuditContext,
   page: PageSnapshot
@@ -33,8 +60,10 @@ const canonicalChecks = (
   if (!page.canonical) {
     // Without `deployment.site` Blume has no absolute URL to canonicalize to, so
     // report the root cause once (in the sitemap/robots checks) rather than
-    // flagging every page for a config field they can't fix individually.
-    return site
+    // flagging every page for a config field they can't fix individually. A
+    // noindex page omits its canonical on purpose — the layouts drop it, since
+    // Google treats the pairing as contradictory (see CANONICAL_ON_NOINDEX).
+    return site && page.indexable
       ? [
           finding(
             "BLUME_AUDIT_CANONICAL_MISSING",
@@ -101,23 +130,14 @@ const canonicalChecks = (
       )
     );
   } else if (context.byUrl.has(target)) {
-    // An archived-version page pointing at its latest equivalent is Blume's
-    // own default (versions.archived[].canonical: "latest"), not a defect —
-    // the live page is the authoritative one by design.
-    const version = page.route?.version;
-    const archived = version
-      ? context.project.config.versions?.archived.find(
-          (entry) => entry.id === version
-        )
-      : undefined;
-    const latestAlternate = page.route?.versionAlternates.find(
-      (alternate) => alternate.version === ""
-    );
-    const intentional =
-      archived?.canonical === "latest" &&
-      latestAlternate !== undefined &&
-      normalizePath(latestAlternate.path) === target;
-    if (!intentional) {
+    // An i18n fallback copy canonicalizes to the page it copies on purpose,
+    // like an archived page to its latest equivalent.
+    if (
+      !(
+        page.route?.fallback === true ||
+        isArchivedLatestCanonical(context, page, target)
+      )
+    ) {
       found.push(
         finding(
           "BLUME_AUDIT_CANONICAL_NOT_SELF",

package/src/audit/checks/links.ts

@@ -100,6 +100,20 @@ export const linkChecks: CheckModule = {
       if (resolved.kind === "external" || resolved.kind === "ignored") {
         return;
       }
+      if (resolved.kind === "outside-base") {
+        if (link.content) {
+          found.push(
+            finding(
+              "BLUME_AUDIT_LINK_TO_BROKEN",
+              pageSite(context, page),
+              `Link to ${link.href} is missing deployment.base (${deployBase}), so the deployed site does not serve it.`
+            )
+          );
+        } else if (!brokenChrome.has(resolved.path)) {
+          brokenChrome.set(resolved.path, page);
+        }
+        return;
+      }
 
       const anchorTarget = resolved.hash
         ? context.byUrl.get(resolved.path)

package/src/audit/checks/llms.ts

@@ -113,15 +113,18 @@ export const llmsChecks: CheckModule = {
 
     // The reverse direction, mirroring INDEXABLE_PAGE_NOT_IN_SITEMAP: a page
     // that is built, indexable, and in the nav belongs in the index. Pages the
-    // generator deliberately skips — hidden, drafts, error routes, API
-    // reference when `agents.llmsTxt.openapi` is off, custom pages with no
-    // manifest route — are skipped here for the same reasons.
+    // generator deliberately skips — hidden, drafts, `ai.exclude`, i18n
+    // fallback copies, error routes, API reference when
+    // `agents.llmsTxt.openapi` is off, custom pages with no manifest route —
+    // are skipped here for the same reasons.
     for (const page of context.pages) {
       const { route } = page;
       if (
         !route ||
         route.hidden ||
         route.draft ||
+        route.aiExclude ||
+        route.fallback ||
         !page.indexable ||
         ERROR_ROUTES.has(page.url) ||
         (!openapi && route.source.name === "openapi") ||