blume 1.4.2 → 1.5.0

package/src/astro/templates.ts

@@ -37,6 +37,8 @@ const hasWorkspacesField = (pkgPath: string): boolean => {
     return false;
   }
   try {
+    // SAFETY: parsed from the user's own package.json; only the presence of a
+    // `workspaces` field is read, so this loose shape is all the cast claims.
     const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
       workspaces?: unknown;
     };
@@ -71,16 +73,19 @@ const findWorkspaceRoot = (start: string): string => {
   }
 };
 
-const ADAPTER_IMPORTS: Record<string, string> = {
+type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+const ADAPTER_IMPORTS = {
   cloudflare: "@astrojs/cloudflare",
   netlify: "@astrojs/netlify",
   node: "@astrojs/node",
   vercel: "@astrojs/vercel",
-};
+} satisfies Record<DeploymentAdapter, string>;
 
-const ADAPTER_OPTIONS: Record<string, string> = {
-  node: '{ mode: "standalone" }',
-};
+/** Adapter constructor arguments, for the adapters that need any. */
+const ADAPTER_OPTIONS = new Map<DeploymentAdapter, string>([
+  ["node", '{ mode: "standalone" }'],
+]);
 
 const WRANGLER_CONFIG_FILES = [
   "wrangler.jsonc",
@@ -169,8 +174,8 @@ export const runtimeDependencies = (options: {
     deps.push("@astrojs/svelte");
   }
   // The Scalar integration is only declared for a Scalar-rendered reference
-  // (the `renderer: "scalar"` fallback, or AsyncAPI). Blume-rendered OpenAPI
-  // parses at generate time and needs no runtime Scalar dependency.
+  // (the `renderer: "scalar"` opt-out on either block). Blume-rendered
+  // references parse at generate time and need no runtime Scalar dependency.
   if (hasScalarReferences(config)) {
     deps.push("@scalar/astro");
   }
@@ -370,6 +375,12 @@ const renderImageOption = (config: ResolvedConfig): string =>
     ? `\n  image: ${JSON.stringify(config.image)},`
     : "";
 
+/** What `resolveOptimizeDeps` feeds the generated `optimizeDeps` block. */
+interface OptimizeDepsConfig {
+  optimizeDepsEntries: string[];
+  optimizeDepsInclude: string[];
+}
+
 /**
  * Startup-scan entry points and forced includes for the dev dep optimizer:
  * the Vite root is the generated runtime, so user pages, convention islands,
@@ -383,7 +394,7 @@ const resolveOptimizeDeps = (options: {
   context: ProjectContext;
   needsReact: boolean;
   reactCompilerPath: string | null | undefined;
-}): { optimizeDepsEntries: string[]; optimizeDepsInclude: string[] } => {
+}): OptimizeDepsConfig => {
   const { context } = options;
   const optimizeDepsEntries = [
     ...(context.pagesRoot ? [`${context.pagesRoot}/**/*.astro`] : []),
@@ -474,7 +485,7 @@ export const astroConfigTemplate = (options: {
     if (deployment.adapter === "cloudflare") {
       return resolveCloudflareAdapterArgs(context);
     }
-    return ADAPTER_OPTIONS[deployment.adapter] ?? "";
+    return ADAPTER_OPTIONS.get(deployment.adapter) ?? "";
   })();
   // Vercel resolves its Build Output tree and its `@vercel/nft` dependency
   // trace against the Astro root, which for Blume is the hidden `.blume`
@@ -547,19 +558,23 @@ export const astroConfigTemplate = (options: {
               )}, fallbacks: ${JSON.stringify(
                 font.fallbacks
               )}, options: { variants: ${JSON.stringify(
-                font.variants.map((variant) => ({
-                  ...(variant.weight === undefined
-                    ? {}
-                    : { weight: variant.weight }),
-                  ...(variant.style === undefined
-                    ? {}
-                    : { style: variant.style }),
-                  src: [
-                    isAbsolute(variant.src)
-                      ? variant.src
-                      : join(context.root, variant.src),
-                  ],
-                }))
+                font.variants.map((variant) => {
+                  const face: Pick<typeof variant, "style" | "weight"> = {};
+                  if (variant.weight !== undefined) {
+                    face.weight = variant.weight;
+                  }
+                  if (variant.style !== undefined) {
+                    face.style = variant.style;
+                  }
+                  return {
+                    ...face,
+                    src: [
+                      isAbsolute(variant.src)
+                        ? variant.src
+                        : join(context.root, variant.src),
+                    ],
+                  };
+                })
               )} } }`
             : `{ provider: fontProviders.${font.provider}(), name: ${JSON.stringify(
                 font.name
@@ -868,11 +883,24 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 };
 
 /** Generate `.blume/src/pages/[...slug].astro`, the docs catch-all route. */
-/** Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`). */
+/** The plain prompt used when there is no grounding context to inject. */
+const ASK_FALLBACK_PROMPT =
+  "You are a helpful documentation assistant. Answer using the project's documentation.";
+
+/**
+ * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
+ * `instructions` (the `ai.ask.instructions` config) is appended to the
+ * built-in prompt on every path: the grounded prompt via `createAskContext`,
+ * and the plain fallback here.
+ */
 export const askEndpointTemplate = (
   backend: AskBackend,
-  grounded: boolean
+  grounded: boolean,
+  instructions?: string
 ): string => {
+  const fallbackPrompt = instructions
+    ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
+    : ASK_FALLBACK_PROMPT;
   const imports = [
     'import type { APIRoute } from "astro";',
     'import { streamText } from "ai";',
@@ -905,7 +933,10 @@ export const askEndpointTemplate = (
       'import { createAskContext } from "blume/ai/ask-context.ts";',
       'import askData from "../../generated/ask-data.json";'
     );
-    setup += "\nconst ground = createAskContext(askData);\n";
+    const groundOptions = instructions
+      ? `, { instructions: ${JSON.stringify(instructions)} }`
+      : "";
+    setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
   }
   // Validate the client-supplied body and cap its size. The endpoint is
   // unauthenticated, so bounding message count/length limits how much a caller
@@ -966,7 +997,7 @@ export const askEndpointTemplate = (
   const stream = grounded
     ? `    const instructions =
       (await ground(messages, body.page)) ??
-      "You are a helpful documentation assistant. Answer using the project's documentation.";
+      ${JSON.stringify(fallbackPrompt)};
     const result = streamText({
       model: ${modelExpr},
       instructions,
@@ -976,7 +1007,7 @@ ${onError}
     : `    const result = streamText({
       model: ${modelExpr},
       instructions:
-        "You are a helpful documentation assistant. Answer using the project's documentation.",
+        ${JSON.stringify(fallbackPrompt)},
       messages,
 ${onError}
     });`;
@@ -1079,10 +1110,17 @@ export const createSearch = () => create({ indexUrl${
   } });
 `;
 
+/**
+ * Public credential fields baked into a hosted provider's generated client
+ * (Algolia/Orama Cloud/Typesense config values from `search.*`, all plain
+ * strings or numbers; `JSON.stringify` drops the absent ones).
+ */
+type HostedSearchCredentials = Record<string, string | number | undefined>;
+
 /** A client that passes public credentials straight to the provider SDK. */
 const hostedSearchClient = (
   module: string,
-  options: Record<string, unknown>
+  options: HostedSearchCredentials
 ): string =>
   `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}
 export const createSearch = () => create(${JSON.stringify(options)});
@@ -1091,7 +1129,7 @@ export const createSearch = () => create(${JSON.stringify(options)});
 /** Build the per-provider config object the hosted client is created with. */
 const hostedSearchOptions = (
   search: ResolvedConfig["search"]
-): { module: string; options: Record<string, unknown> } | null => {
+): { module: string; options: HostedSearchCredentials } | null => {
   switch (search.provider) {
     case "algolia": {
       return { module: "algolia", options: { ...search.algolia } };
@@ -1261,7 +1299,7 @@ export const contentAssetsEndpointTemplate = (
   `// Generated by Blume. Do not edit.
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import type { APIRoute } from "astro";
 import assets from "../../generated/content-assets.json";
 
@@ -1321,7 +1359,13 @@ const resolveAsset = (asset: string): string | 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.
-  if (!abs.startsWith(STAGED_DIR + "/")) {
+  // path.relative rather than a string-prefix test: STAGED_DIR is baked in
+  // with forward slashes while resolve() answers in the platform's
+  // separators, so on Windows the prefix test 404'd every legitimate staged
+  // 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)) {
     return null;
   }
   return existsSync(abs) ? abs : null;
@@ -1367,7 +1411,9 @@ export const ALL: APIRoute = ({ request }) => handler(request);
 };
 
 /** Generate a prerendered endpoint that serves a fixed JSON payload. */
-export const staticJsonEndpointTemplate = (payload: unknown): string =>
+export const staticJsonEndpointTemplate = <Payload extends object>(
+  payload: Payload
+): string =>
   `// Generated by Blume. Do not edit.
 export const prerender = true;
 
@@ -1488,8 +1534,9 @@ export async function GET({ props }: { props: { title: string } }) {
  * live inside our shell. `dataImport` is the route-depth-aware relative path to
  * the generated data module the layout reads.
  */
-export const scalarReferenceTemplate = (options: {
-  configuration: Record<string, unknown>;
+export const scalarReferenceTemplate = <Configuration extends object>(options: {
+  /** Scalar options forwarded verbatim (spec/theme config plus the author's `scalar` escape hatch). */
+  configuration: Configuration;
   dataImport: string;
   noindex?: boolean;
   route: string;
@@ -1665,11 +1712,13 @@ export function getStaticPaths() {
       locale: route.locale,
       route: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     },
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -1680,8 +1729,11 @@ const frontmatter = entry.data ?? {};
 const seo = frontmatter.seo ?? {};
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 
+// Percent-encode the route-derived path (the sitemap convention): a Unicode
+// slug (\`/api/größe\`) is not legal in a raw URI, and crawlers compare
+// canonical against the sitemap's encoded <loc> byte-for-byte.
 const ogPath = data.config.og.enabled
-  ? \`/og/\${route === "/" ? "index" : route.slice(1)}.png\`
+  ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
 const ogRel = seo.image ?? ogPath;
 // Absolute URLs also carry the deployment base (the page is served under it):
@@ -1698,9 +1750,6 @@ const ogGenerated = !seo.image && Boolean(ogPath);
 const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
 const basedRoute = withBase(route);
-const canonical =
-  seo.canonical ??
-  (base ? \`\${base}\${basedRoute === "/" ? "" : basedRoute}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -1721,7 +1770,20 @@ const stripLocale = (path: string, codeArg: string) => {
   return prefix && path.startsWith(prefix) ? path.slice(prefix.length) || "/" : path;
 };
 
-const navigation = i18n ? (data.navigationByLocale[locale] ?? data.navigation) : data.navigation;
+// Version resolution. An archived page renders its snapshot's navigation tree,
+// points its canonical at the latest equivalent (unless configured otherwise),
+// and shows the old-version notice.
+const versionsConfig = data.config.versions;
+const archived = versionsConfig && version
+  ? (versionsConfig.archived.find((v) => v.id === version) ?? null)
+  : null;
+const latestVersionAlt = (versionAlternates ?? []).find((alt) => alt.version === "");
+
+const navigation = version
+  ? (data.navigationByVersion[version]?.[i18n ? locale : ""] ?? data.navigation)
+  : i18n
+    ? (data.navigationByLocale[locale] ?? data.navigation)
+    : data.navigation;
 const ui = i18n ? (data.uiByLocale[locale] ?? data.ui) : data.ui;
 const localeMeta = i18n ? i18n.locales.find((l) => l.code === locale) : null;
 const dir = localeMeta?.dir ?? "ltr";
@@ -1738,6 +1800,19 @@ const absolute = (path: string) => {
   return base + (p === "/" ? "" : p);
 };
 
+// An archived page defaults its canonical to the same page in the latest docs
+// when that page still exists — search engines treat the live page as
+// authoritative without deindexing version-only content. A page's own
+// \`seo.canonical\` always wins, and \`canonical: "self"\` keeps the default.
+const canonical =
+  seo.canonical ??
+  (archived && archived.canonical === "latest" && latestVersionAlt && base
+    ? absolute(latestVersionAlt.path)
+    : base
+      ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\`
+      : null);
+const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
+
 const localeAlternates =
   i18n && base
     ? (alternates ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
@@ -1760,6 +1835,72 @@ const localeSwitch = i18n
     })
   : [];
 
+// Version switcher + old-version notice. The switcher auto-populates from the
+// versions config as a \`kind: "version"\` selector; a user-declared version
+// selector in \`navigation.selectors\` suppresses it (theirs renders instead).
+// Fallback version roots compose like real routes — \`{basePath}/{locale?}/{id}\`
+// (manifest \`versionAlternates\` paths arrive with the base already applied).
+const versionRootFor = (id: string) => {
+  const logical = id ? \`/\${id}\` : "/";
+  const localized = i18n ? localizeRoute(logical, locale) : logical;
+  const mount = data.config.basePath;
+  if (!mount) {
+    return localized;
+  }
+  return localized === "/" ? mount : \`\${mount}\${localized}\`;
+};
+const samePageSwitch = versionsConfig
+  ? versionsConfig.switcher.redirect === "same-page"
+  : true;
+const userHasVersionSelector = navigation.selectors.some(
+  (selector) => selector.kind === "version"
+);
+const versionSelector =
+  versionsConfig && !userHasVersionSelector
+    ? {
+        items: [
+          {
+            id: "",
+            label: versionsConfig.current.label,
+            tag: versionsConfig.current.badge,
+          },
+          ...versionsConfig.archived.map((v) => ({
+            id: v.id,
+            label: v.label ?? v.id,
+            tag: undefined,
+          })),
+        ].map((entry) => {
+          const alt = (versionAlternates ?? []).find(
+            (a) => a.version === entry.id
+          );
+          return {
+            label: entry.label,
+            path: samePageSwitch && alt ? alt.path : versionRootFor(entry.id),
+            ...(entry.tag ? { tag: entry.tag } : {}),
+          };
+        }),
+        kind: "version" as const,
+        label: ui.versions.switcher,
+      }
+    : null;
+
+const versionNotice =
+  archived && archived.banner !== false
+    ? {
+        latestHref: latestVersionAlt
+          ? latestVersionAlt.path
+          : versionRootFor(""),
+        latestLabel: ui.versions.latest,
+        message:
+          typeof archived.banner === "string"
+            ? archived.banner
+            : ui.versions.notice.replace(
+                "{version}",
+                archived.label ?? archived.id
+              ),
+      }
+    : null;
+
 // The whole page shell is overridable via \`layout.Layout\`; it receives the same
 // props as the built-in RootLayout, plus the \`layout\` map for its inner slots.
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
@@ -1784,6 +1925,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   localeAlternates={localeAlternates}
   xDefault={xDefault}
   localeSwitch={localeSwitch}
+  versionSelector={versionSelector}
+  versionNotice={versionNotice}
+  searchVersion={versionsConfig ? version : null}
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
   toc={data.config.toc}
@@ -1806,7 +1950,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   pageType={frontmatter.type}
   published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
   lastModified={lastModified}
-  noindex={seo.noindex}
+  noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
 >
   <h1>{title}</h1>

package/src/audit/agent.ts

@@ -1,7 +1,7 @@
-import { spawn } from "node:child_process";
 import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 
+import spawn from "cross-spawn";
 import { join } from "pathe";
 
 import { reportJson } from "./report.ts";
@@ -19,7 +19,7 @@ export interface AgentCli {
 
 export type AgentKind = "claude" | "codex";
 
-export const AGENTS: Record<AgentKind, AgentCli> = {
+export const AGENTS = {
   claude: {
     bin: "claude",
     install: "npm install -g @anthropic-ai/claude-code",
@@ -30,7 +30,7 @@ export const AGENTS: Record<AgentKind, AgentCli> = {
     install: "npm install -g @openai/codex",
     name: "Codex",
   },
-};
+} satisfies Record<AgentKind, AgentCli>;
 
 /**
  * Write the full JSON report where the agent can read it. A file rather than
@@ -61,37 +61,26 @@ Work through every finding:
 
 When you are done, run \`blume build\` and then \`blume audit\` to verify, and repeat until the audit reports no issues.`;
 
-const spawnAgent = (
-  command: string,
-  args: string[],
-  shell: boolean
-): Promise<number> =>
+const spawnAgent = (bin: string, args: string[]): Promise<number> =>
   // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
   new Promise((resolve, reject) => {
-    const child = spawn(command, args, { shell, stdio: "inherit" });
+    const child = spawn(bin, args, { stdio: "inherit" });
     child.once("error", reject);
     child.once("close", (code) => resolve(code ?? 1));
   });
 
-/**
- * cmd.exe reports a missing executable through this exit code instead of a
- * spawn error, so a shell launch can't rely on the `error` event for the
- * "not installed" diagnosis.
- */
-export const WINDOWS_COMMAND_NOT_FOUND = 9009;
-
 /**
  * Run the agent CLI interactively with the handoff prompt, inheriting the
  * terminal so the user watches and steers the fixes rather than granting a
  * headless process blanket write access. Resolves with the agent's exit code;
- * rejects when the executable isn't on PATH.
+ * rejects when the executable isn't on PATH — on every platform, since
+ * cross-spawn resolves npm's `.cmd` shims itself and escapes their arguments
+ * (the old `shell: true` launch left quoting to a hand-built command line and
+ * reported a missing executable as cmd.exe's exit code 9009).
  *
- * On Windows, npm installs agent CLIs as `.cmd` shims, which Node refuses to
- * spawn without a shell — and cmd.exe cannot carry the multi-line prompt as an
- * argument (a newline ends the command). So there the prompt is written to a
- * file next to the report and handed over via a one-line pointer that survives
- * cmd.exe quoting; a missing executable surfaces as
- * {@link WINDOWS_COMMAND_NOT_FOUND} rather than a rejection.
+ * cmd.exe still cannot carry the multi-line prompt as an argument (a newline
+ * ends the command), so on Windows the prompt is written to a file next to
+ * the report and handed over via a one-line pointer.
  */
 export const launchAgent = async (
   bin: string,
@@ -99,16 +88,12 @@ export const launchAgent = async (
   platform: NodeJS.Platform = process.platform
 ): Promise<number> => {
   if (platform !== "win32") {
-    return await spawnAgent(bin, [prompt], false);
+    return await spawnAgent(bin, [prompt]);
   }
   const dir = await mkdtemp(join(tmpdir(), "blume-audit-"));
   const promptPath = join(dir, "prompt.md");
   await writeFile(promptPath, prompt);
-  // Double quotes are the one grouping cmd.exe respects; neither the temp
-  // path nor the fixed pointer text can contain one.
-  return await spawnAgent(
-    `"${bin}" "Read ${promptPath} and follow its instructions exactly."`,
-    [],
-    true
-  );
+  return await spawnAgent(bin, [
+    `Read ${promptPath} and follow its instructions exactly.`,
+  ]);
 };

package/src/audit/checks/content.ts

@@ -1,3 +1,5 @@
+import stringWidth from "string-width";
+
 import matter from "../../core/frontmatter.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
@@ -5,6 +7,17 @@ import { pageSite } from "../locate.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 
+// Extraction trims only the ends; interior runs of whitespace (a <title>
+// authored across indented source lines) survive. A search engine collapses
+// them to single spaces before rendering, so the width is measured on the
+// collapsed text — source formatting must not move a page across a threshold.
+const WHITESPACE = /\s+/gu;
+
+/** Whether front matter `date` arrived in one of YAML's two date spellings. */
+const isDateValue = (
+  value: string | Date | undefined
+): value is string | Date => typeof value === "string" || value instanceof Date;
+
 /**
  * The `date` a source file's front matter declares, when it parses to a real
  * date. YAML hands back a `Date` for an unquoted `2026-01-01` and a string for
@@ -14,8 +27,8 @@ import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
  */
 const frontmatterDate = (source: string): Date | null => {
   try {
-    const { date } = matter(source).data as { date?: unknown };
-    if (typeof date !== "string" && !(date instanceof Date)) {
+    const { date } = matter(source).data;
+    if (!isDateValue(date)) {
       return null;
     }
     const parsed = date instanceof Date ? date : new Date(date);
@@ -52,13 +65,16 @@ const titleChecks = (
       )
     );
   }
-  if (title.length > titleMax || title.length < titleMin) {
-    const direction = title.length > titleMax ? "long" : "short";
+  // Columns, not characters: a search engine truncates by the space the text
+  // takes up. See {@link AuditThresholds}.
+  const width = stringWidth(title.replaceAll(WHITESPACE, " "));
+  if (width > titleMax || width < titleMin) {
+    const direction = width > titleMax ? "long" : "short";
     found.push(
       finding(
         "BLUME_AUDIT_TITLE_LENGTH",
         pageSite(context, page, ["title"]),
-        `Title is ${title.length} characters — too ${direction} (aim for ${titleMin}–${titleMax}).`
+        `Title renders ${width} columns wide — too ${direction} (aim for ${titleMin}–${titleMax}).`
       )
     );
   }
@@ -99,16 +115,15 @@ const descriptionChecks = (
       )
     );
   }
-  if (
-    description.length > descriptionMax ||
-    description.length < descriptionMin
-  ) {
-    const direction = description.length > descriptionMax ? "long" : "short";
+  // Columns, not characters. See {@link AuditThresholds}.
+  const width = stringWidth(description.replaceAll(WHITESPACE, " "));
+  if (width > descriptionMax || width < descriptionMin) {
+    const direction = width > descriptionMax ? "long" : "short";
     found.push(
       finding(
         "BLUME_AUDIT_DESCRIPTION_LENGTH",
         pageSite(context, page, ["description"]),
-        `Meta description is ${description.length} characters — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
+        `Meta description renders ${width} columns wide — too ${direction} (aim for ${descriptionMin}–${descriptionMax}).`
       )
     );
   }

package/src/audit/checks/dns-aid.ts

@@ -68,6 +68,9 @@ const fetchDohJson = async (
     if (!response.ok) {
       return null;
     }
+    // SAFETY: the resolver answered a dns-json query, whose response schema
+    // DohResponse models with every field optional; a malformed body that
+    // fails to parse rejects into the catch below.
     return (await response.json()) as DohResponse;
   } catch {
     return null;

package/src/audit/checks/indexability.ts

@@ -101,13 +101,31 @@ const canonicalChecks = (
       )
     );
   } else if (context.byUrl.has(target)) {
-    found.push(
-      finding(
-        "BLUME_AUDIT_CANONICAL_NOT_SELF",
-        pageSite(context, page, ["seo", "canonical"]),
-        `Page declares ${target} as its canonical, so it will not be indexed itself.`
-      )
+    // 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) {
+      found.push(
+        finding(
+          "BLUME_AUDIT_CANONICAL_NOT_SELF",
+          pageSite(context, page, ["seo", "canonical"]),
+          `Page declares ${target} as its canonical, so it will not be indexed itself.`
+        )
+      );
+    }
   } else {
     found.push(
       finding(

package/src/audit/checks/llms.ts

@@ -6,12 +6,17 @@ import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
 import { normalizePath, siteOrigin } from "../url.ts";
 
+/** The object form of `ai.llmsTxt`. The schema always emits it, but hand-built
+ * audit contexts (tests, partial configs) may still carry the raw boolean. */
+const isLlmsToggleObject = (
+  value: boolean | { enabled: boolean; openapi: boolean } | undefined
+): value is { enabled: boolean; openapi: boolean } =>
+  typeof value === "object" && value !== null;
+
 /** The `ai.llmsTxt` config normalized to what the checks need. */
-const llmsConfig = (
-  context: AuditContext
-): { enabled: boolean; openapi: boolean } => {
+const llmsConfig = (context: AuditContext) => {
   const value = context.project.config.ai?.llmsTxt;
-  if (typeof value === "object" && value !== null) {
+  if (isLlmsToggleObject(value)) {
     return { enabled: value.enabled, openapi: value.openapi };
   }
   return { enabled: value !== false, openapi: true };

package/src/audit/checks/network.ts

@@ -252,6 +252,8 @@ export const externalChecks: CheckModule = {
       if (!result) {
         continue;
       }
+      // SAFETY: every `linkers` entry is created with its linking page and only
+      // ever appended to, so the array is never empty.
       const site = pageSite(context, pages[0] as PageSnapshot);
 
       const grade = gradeExternal(result);