blume 1.0.4 → 1.1.0

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

@@ -37,7 +37,7 @@ Resolve `$ref` includes first (Mintlify splits config across files). Map only wh
 | `variables` (`{{name}}`) | **inline into content** | Blume has no runtime `{{var}}` substitution — replace each `{{name}}` with its value in the pages |
 | `integrations.posthog` (`{ apiKey, apiHost }`) | `analytics.posthog` (`{ key, host }`) | preserve the host verbatim (e.g. `us.posthog.com` — Blume's default is `us.i.posthog.com`) |
 | `integrations` (GA, Plausible, Fathom, …) | `analytics.scripts` / `analytics.vercel` | one `scripts[]` entry per provider (`{ src, strategy, attributes }`); no first-class mapping beyond PostHog/Vercel |
-| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `mcp.enabled` + server output (report as a follow-up) |
+| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `ai.mcp.enabled` + server output (report as a follow-up) |
 | `redirects` | `redirects: [{ from, to }]` | static only — see below |
 | `navigation.languages` | `i18n` | see i18n below |
 
@@ -107,7 +107,8 @@ Rewrite each page's MDX:
 - **Callouts → directives** (directives are **MDX-only** — Mintlify content is already `.mdx`, so this just works; never rename a page to `.md`): `<Note>`→`:::note`, `<Tip>`→`:::tip`, `<Warning>`→`:::warning`, `<Info>`→`:::info`, `<Check>`→`:::success`, `<Danger>`/`<Error>`→`:::danger`. `<Callout type="x">` maps by type (`caution`→warning, `check`→success). A `title` attr → `:::type[Title]`. Drop `icon`/color props.
 - **Accordions — container/item inversion!** Mintlify nests `<Accordion title="…">` inside `<AccordionGroup>`. Blume inverts: `<AccordionGroup>`→`<Accordion>` (container), and each Mintlify `<Accordion title="…">`→`<AccordionItem title="…">` (item).
 - **`<RequestExample>`/`<ResponseExample>`** → `<CodeGroup>` (titled-fence tabs).
-- **These pass through — Blume ships them natively:** `<Columns>`/`<Column>`, `<Expandable>`, `<Tooltip>`, `<Frame>`, `<Panel>`, `<Card>`/`<CardGroup>`, `<Tabs>`/`<Tab>`, `<Steps>`/`<Step>`. Keep them as-is.
+- **`<Tabs>` → `<Tabs inline>`.** Mintlify renders tabs **borderless** — a strip on a full-width rule with the content flowing beneath as prose — while Blume's `<Tabs>` defaults to a bordered box. Add `inline` to each `<Tabs>` to preserve Mintlify's appearance; every child `<Tab title="…">` is unchanged. Don't add `param` — Mintlify tabs switch in place and don't deep-link to the URL, so plain `inline` is the faithful mapping.
+- **These pass through — Blume ships them natively:** `<Columns>`/`<Column>`, `<Expandable>`, `<Tooltip>`, `<Frame>`, `<Panel>`, `<Card>`/`<CardGroup>`, `<Tab>`, `<Steps>`/`<Step>`. Keep them as-is.
 - **API fields → `TypeTable`.** Blume does **not** ship `<ParamField>`/`<ResponseField>`/`<RequestField>`. Convert a cluster of fields into one `<TypeTable>` (rows keyed by field name, each `{ type, required?, default?, description }`). For a fully spec'd API, prefer deleting the hand-written fields and using the [OpenAPI reference](#openapi) instead.
 - **`<Update>`** (a Mintlify changelog entry) has no component form → convert to a `type: changelog` page, or use the `github-releases` source.
 - **Snippets are inlined, not imported.** Blume has no `/snippets` import mechanism. For each `import X from "/snippets/x.mdx"` + `<X prop="v" />`, inline the snippet's body (substituting `{prop}` placeholders), then delete the import and the `/snippets` file. Named string imports (`import { foo } from "/snippets/vars.mdx"`) → inline the value at each `{foo}`.

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -277,7 +277,8 @@ const remapIcons = (fm) => {
       continue;
     }
     if (lucide !== raw) {
-      fm[i] = `${m.groups.indent}icon: ${lucide}`;
+      const comment = m.groups.comment ? ` ${m.groups.comment}` : "";
+      fm[i] = `${m.groups.indent}icon: ${lucide}${comment}`;
       changes.push({ detail: `${raw} → ${lucide}`, kind: "icon-remap" });
     }
     i += 1;
@@ -301,11 +302,12 @@ const setNested = (fm, parent, child, value) => {
       return { ok: false, reason: "child-exists" };
     }
     fm.splice(start + 1, 0, `  ${child}: ${value}`);
-    return { ok: true };
+    return { index: start + 1, ok: true };
   }
   // No parent block — append one at the end of the frontmatter.
+  const index = fm.length;
   fm.push(`${parent}:`, `  ${child}: ${value}`);
-  return { ok: true };
+  return { index, ok: true };
 };
 
 // Drop unsupported keys, rename Mintlify-only keys, flag ambiguous ones.
@@ -341,14 +343,24 @@ const rewriteFields = (fm) => {
       });
       continue;
     }
+    // Remove the source line before inserting: setNested splices into the
+    // parent block, and when that block sits above the source key the insert
+    // would otherwise shift `start` onto the wrong line. Failure paths don't
+    // mutate `fm`, so the line can be restored as-is on conflict.
+    const [removed] = fm.splice(start, 1);
     const placed = setNested(fm, parent, child, tk.value);
     if (placed.ok) {
-      fm.splice(start, 1);
+      if (placed.index < start) {
+        // The insert above the cursor pushed the unvisited lines down one
+        // slot; revisit the current index so none of them get skipped.
+        i += 1;
+      }
       changes.push({
         detail: `${tk.key} → ${parent}.${child}`,
         kind: "rename",
       });
     } else {
+      fm.splice(start, 0, removed);
       // Target already set, or parent is a scalar — leave the source in place so
       // no data is lost, and report it for manual resolution.
       changes.push({

package/src/ai/llms.ts

@@ -3,6 +3,7 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
+import { buildRssFeeds } from "../deploy/rss.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
@@ -136,6 +137,20 @@ const buildIndex = (project: BlumeProject): string => {
     );
   }
 
+  // Surface the RSS feeds so agents can find fresh content (new blog posts,
+  // changelog entries) without re-crawling the index. `buildRssFeeds` is empty
+  // unless RSS is enabled and an absolute `site` is set — the same condition
+  // under which agent-readability.json lists `artifacts.feeds`.
+  const feeds = buildRssFeeds(project);
+  if (feeds.length > 0) {
+    blocks.push(
+      "## RSS Feeds",
+      feeds
+        .map((feed) => `- [${feed.title}](${pageUrl(feed.path, site, base)})`)
+        .join("\n")
+    );
+  }
+
   const header = config.description
     ? `# ${config.title}\n\n> ${config.description}`
     : `# ${config.title}`;

package/src/astro/adapter-root.ts

@@ -0,0 +1,70 @@
+import { pathToFileURL } from "node:url";
+
+import type { AstroIntegration } from "astro";
+
+/**
+ * Present a deploy adapter with `root` pointed at the real project root rather
+ * than the hidden `.blume` runtime.
+ *
+ * Astro's `root` and `outDir` normally sit together (`outDir` defaults to
+ * `<root>/dist`), and `@astrojs/vercel` leans on that: it writes its Build
+ * Output tree to `<root>/.vercel/output` and — the part that bites — traces the
+ * function's dependency closure with `@vercel/nft` using a base derived from
+ * `root`, silently dropping every traced file that falls outside it.
+ *
+ * Blume splits the two: `root` is `<project>/.blume`, so Astro resolves the
+ * runtime's own `package.json` and its `node_modules` junction, while `outDir`
+ * stays at `<project>/dist` so the build lands where users expect. That puts
+ * `build.server` (`<outDir>/server`) *outside* `root`, so nft's base excludes
+ * the server bundle entirely: the traced file list collapses to `entry.mjs`
+ * alone, and the deployed function dies on its first import with
+ * ERR_MODULE_NOT_FOUND — missing its chunks, its virtual middleware, and every
+ * npm dependency.
+ *
+ * A project inside a workspace accidentally escapes this, because nft's base
+ * search climbs past `.blume` to the workspace root, which does contain both
+ * `dist/` and `node_modules` — which is why the bug only ever surfaced in
+ * standalone projects.
+ *
+ * Handing the adapter the root its own `outDir` assumption implies restores the
+ * invariant without moving Astro's real root: the trace covers `dist/server`
+ * and `node_modules`, and the Build Output tree lands at the project root
+ * natively, where `vercel deploy --prebuilt` looks for it.
+ *
+ * `astro:config:setup` and `astro:config:done` are the only hooks handed a
+ * `config`; an adapter reads `root` from one or both and closes over it for its
+ * later build hooks, so overriding it there covers the whole adapter.
+ */
+const stripTrailingSlashes = (value: string): string => {
+  let end = value.length;
+
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+
+  return value.slice(0, end);
+};
+
+export const withAdapterRoot = (
+  integration: AstroIntegration,
+  root: string
+): AstroIntegration => {
+  const rootUrl = pathToFileURL(`${stripTrailingSlashes(root)}/`);
+  const setup = integration.hooks["astro:config:setup"];
+  const done = integration.hooks["astro:config:done"];
+
+  return {
+    ...integration,
+    hooks: {
+      ...integration.hooks,
+      ...(setup && {
+        "astro:config:setup": (options) =>
+          setup({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+      ...(done && {
+        "astro:config:done": (options) =>
+          done({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+    },
+  };
+};

package/src/astro/generate.ts

@@ -29,7 +29,10 @@ import type {
 } from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
-import { validateNavTargets } from "../core/nav-diagnostics.ts";
+import {
+  validateNavTargets,
+  validateSearchPopularIcons,
+} from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
@@ -43,6 +46,7 @@ import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import { resolveSearchPopular } from "../search/popular.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import {
   examplesEntryTemplate,
@@ -145,23 +149,42 @@ const reactCompilerWarnings = (
       ]
     : [];
 
-/**
- * Realpath of the `astro` package node resolves from a directory, or null when
- * none resolves. Comparing this for `.blume/` against Blume's own deps tells
- * whether the runtime would bind to the *same* astro Blume uses or a different
- * one shadowing it (the hoisted-conflict failure mode).
- */
-const resolvedAstroPath = (fromDir: string): string | null => {
+/** Resolve Astro's package.json directly inside a node_modules directory. */
+const resolveAstroPackageJson = (modulesDir: string): string | null => {
   try {
-    const pkg = createRequire(
-      pathToFileURL(join(fromDir, "_.js")).href
-    ).resolve("astro/package.json");
-    return realpathSync(pkg);
+    return realpathSync(join(modulesDir, "astro", "package.json"));
   } catch {
     return null;
   }
 };
 
+/**
+ * Realpath of the `astro` package reachable through the normal node_modules
+ * ancestor walk from a generated runtime, or null when none resolves.
+ *
+ * This deliberately does not use `createRequire().resolve()`. pnpm's generated
+ * bin shim adds Blume's virtual-store dependencies to `NODE_PATH`, which
+ * CommonJS resolution honors but ESM package resolution ignores. The generated
+ * Astro config uses ESM imports, so treating a NODE_PATH-only result as
+ * reachable skips the dependency link and makes `import "astro/config"` fail.
+ * Walking the physical node_modules ancestors mirrors the lookup that config
+ * actually gets.
+ */
+const resolvedAstroPath = (fromDir: string): string | null => {
+  let dir = normalize(fromDir);
+  while (true) {
+    const resolved = resolveAstroPackageJson(join(dir, "node_modules"));
+    if (resolved) {
+      return resolved;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+
 /**
  * Locate the directory that holds Blume's installed dependencies (Astro and its
  * integrations).
@@ -278,7 +301,7 @@ export const ensureDepsLink = async (
   }
   // Already correct when `.blume/` resolves the very same astro Blume's deps
   // provide — the clean hoisted case, nothing to do.
-  const blumeAstro = resolvedAstroPath(depsDir);
+  const blumeAstro = resolveAstroPackageJson(depsDir);
   const outDirAstro = resolvedAstroPath(outDir);
   if (blumeAstro && outDirAstro === blumeAstro) {
     return null;
@@ -299,7 +322,7 @@ export const ensureDepsLink = async (
 
 /**
  * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
- * `@takumi-rs/core`, …) resolvable when Astro executes the static prerender
+ * `takumi-js`, …) resolvable when Astro executes the static prerender
  * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
  *
  * Astro's static build emits a self-contained SSR bundle to
@@ -931,12 +954,14 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       // the optional schema type so the serialized shape stays `boolean`.
       og: {
         enabled: config.seo.og.enabled ?? false,
+        fonts: config.seo.og.fonts ?? [],
         logo: ogLogo,
         palette: config.seo.og.palette,
       },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
+        popular: resolveSearchPopular(config.search.popular, config.basePath),
         provider: config.search.provider,
       },
       site: config.deployment.site ?? null,
@@ -1509,12 +1534,18 @@ export const generateRuntime = async (
   if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
+  // Curated `search.popular` icons live outside the navigation model, so they
+  // miss `validateNavIcons` in the graph build — they're checked here too,
+  // where the search config is known. A typo otherwise just renders the
+  // default glyph.
   warnings.push(
-    ...validateNavTargets(project.graph.navigation, navTargetRoutes).map(
-      (diagnostic) =>
-        diagnostic.suggestion
-          ? `${diagnostic.message} ${diagnostic.suggestion}`
-          : diagnostic.message
+    ...[
+      ...validateNavTargets(project.graph.navigation, navTargetRoutes),
+      ...validateSearchPopularIcons(config.search.popular),
+    ].map((diagnostic) =>
+      diagnostic.suggestion
+        ? `${diagnostic.message} ${diagnostic.suggestion}`
+        : diagnostic.message
     )
   );
 

package/src/astro/index.ts

@@ -1,3 +1,4 @@
+export { withAdapterRoot } from "./adapter-root.ts";
 export {
   generateRuntime,
   prerenderDepsPlugin,

package/src/astro/pages.ts

@@ -6,11 +6,25 @@ import type { BlumePageRoute } from "./integration.ts";
 
 const PAGE_GLOB = ["**/*.astro"];
 
+/**
+ * Astro's routing convention: a file or folder whose name starts with `_` is a
+ * private partial — importable (shared layouts, home-page sections), but never
+ * built into a route. Blume injects pages itself, so it must reproduce the same
+ * exclusion or every `pages/_home/Hero.astro`-style component ships as an HTML
+ * page.
+ */
+const isPrivatePage = (rel: string): boolean =>
+  rel.split("/").some((segment) => segment.startsWith("_"));
+
 /** Map discovered page files to routes; shared by the async/sync discoverers. */
 const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
   files.sort();
-  return files.map((file) => {
+  const routes: BlumePageRoute[] = [];
+  for (const file of files) {
     const rel = relative(pagesRoot, file);
+    if (isPrivatePage(rel)) {
+      continue;
+    }
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
     const parts = withoutExt.split("/");
     // Only a trailing `index` maps to its parent dir; a folder literally named
@@ -19,8 +33,9 @@ const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
       parts.pop();
     }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
-    return { entrypoint: file, pattern };
-  });
+    routes.push({ entrypoint: file, pattern });
+  }
+  return routes;
 };
 
 /**

package/src/astro/templates.ts

@@ -10,7 +10,7 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
-import { applyBaseToRedirects } from "../deploy/redirects.ts";
+import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
@@ -166,11 +166,16 @@ export const runtimeDependencies = (options: {
  * static-prerender Vite environments.
  *
  * Two reasons a dep lands here:
- *   - `@takumi-rs/core` (OG image rendering) is a native NAPI addon that loads a
- *     platform-specific `.node` binding via `createRequire(import.meta.url)`.
- *     Bundling it relocates `import.meta.url` and breaks the binding lookup
- *     ("Cannot find native binding") on other platforms (e.g. the Linux CI
- *     runner), so it must resolve from `node_modules` at runtime instead.
+ *   - `takumi-js` (OG image rendering) loads `@takumi-rs/core`, a native NAPI
+ *     addon that finds its platform-specific `.node` binding via
+ *     `createRequire(import.meta.url)`. Bundling it relocates `import.meta.url`
+ *     and breaks the binding lookup ("Cannot find native binding") on other
+ *     platforms (e.g. the Linux CI runner), so it must resolve from
+ *     `node_modules` at runtime instead. The prerender env matches these by
+ *     exact specifier, so every entry point Blume imports has to be listed:
+ *     the bare `takumi-js` (render) plus `takumi-js/helpers` (the `googleFonts`
+ *     OG-font loader). The `@takumi-rs/*` packages are listed too so the native
+ *     backend is never pulled into a chunk down any transitive path.
  *   - The rest are pure-JS packages kept external so an isolated linker (Bun's
  *     `isolated` mode, pnpm) doesn't bundle their symlinked store copies. When
  *     Vite bundles such a package but leaves its own `node_modules` child
@@ -190,10 +195,13 @@ const RENDER_EXTERNAL_DEPS = [
   "@shikijs/transformers",
   "@takumi-rs/core",
   "@takumi-rs/helpers",
+  "@takumi-rs/wasm",
   "github-slugger",
   "katex",
   "shiki",
   "simple-icons",
+  "takumi-js",
+  "takumi-js/helpers",
   "zod",
 ];
 
@@ -212,6 +220,21 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * The root a deploy adapter is shown, in place of the `.blume` runtime Astro
+ * actually roots at. Adapters assume `outDir` is `<root>/dist` and resolve their
+ * own output (and Vercel's dependency trace) against `root`, so the root implied
+ * by Blume's `outDir` is the one that keeps that assumption true. See
+ * {@link withAdapterRoot}.
+ *
+ * For a normal build that is the project root (`<project>/dist` -> `<project>`).
+ * For a relocated runtime (`blume build --isolated`) it is the runtime dir
+ * itself (`<runtime>/dist` -> `<runtime>`), keeping a verify build's adapter
+ * output self-contained instead of overwriting the real `.vercel/output`.
+ */
+const adapterRoot = (context: ProjectContext): string =>
+  dirname(astroOutDir(context));
+
 /**
  * Excludes Vite's pre-bundled dep cache from @vitejs/plugin-react. Astro's
  * react() replaces the plugin's default `/node_modules/` exclude with just
@@ -296,8 +319,17 @@ export const astroConfigTemplate = (options: {
     }
     return ADAPTER_OPTIONS[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`
+  // runtime — leaving the traced function without its chunks or node_modules.
+  // The other adapters emit into `outDir` (cloudflare, node) or are surfaced
+  // afterwards (netlify), so none of them read `root` this way.
+  const adapterExpr =
+    deployment.adapter === "vercel"
+      ? `withAdapterRoot(adapter(${adapterArgs}), ${JSON.stringify(adapterRoot(context))})`
+      : `adapter(${adapterArgs})`;
   const adapterOption =
-    server && deployment.adapter ? `\n  adapter: adapter(${adapterArgs}),` : "";
+    server && deployment.adapter ? `\n  adapter: ${adapterExpr},` : "";
 
   const siteOption = deployment.site
     ? `\n  site: ${JSON.stringify(deployment.site)},`
@@ -320,10 +352,12 @@ export const astroConfigTemplate = (options: {
     : "";
 
   // Base the redirect paths the same way routes are based, so a redirect lands
-  // under `basePath` too. Astro layers its own `base` (deployment.base) on top.
-  const basedRedirects = applyBaseToRedirects(
+  // under `basePath` too. Astro layers its own `base` (deployment.base) onto
+  // `from` when matching, but never onto `to` — see applyBaseToAstroRedirects.
+  const basedRedirects = applyBaseToAstroRedirects(
     config.redirects,
-    config.basePath
+    config.basePath,
+    deployment.base ?? ""
   );
   const redirectsOption =
     basedRedirects.length > 0
@@ -365,7 +399,13 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
-  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin, serverAppResolvePlugin } from "blume/astro";\n`;
+  const blumeImports = [
+    "blumeIntegration",
+    "prerenderDepsPlugin",
+    "serverAppResolvePlugin",
+    ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
+  ];
+  const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
 
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
@@ -1080,6 +1120,7 @@ export async function GET({ props }: { props: { title: string } }) {
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
     description: data.config.description,
+    fonts: data.config.og.fonts,
     logo: data.config.og.logo,
     palette: data.config.og.palette,
     repo: repoSlug,
@@ -1475,6 +1516,18 @@ const toTime = (value: string | null | undefined) => {
   return Number.isNaN(date.getTime()) ? 0 : date.getTime();
 };
 
+// The changelog is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
+
+// Formatted in the same locale as the chrome, and in UTC, to match the
+// per-page "last updated" stamp.
 const formatDate = (value: string | null | undefined) => {
   if (!value) {
     return;
@@ -1482,7 +1535,7 @@ const formatDate = (value: string | null | undefined) => {
   const date = new Date(value);
   return Number.isNaN(date.getTime())
     ? undefined
-    : new Intl.DateTimeFormat("en", {
+    : new Intl.DateTimeFormat(htmlLang, {
         dateStyle: "long",
         timeZone: "UTC",
       }).format(date);
@@ -1579,16 +1632,6 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
-// The changelog is an unlocalized route, so its chrome renders in the default
-// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
-// dictionary), mirroring the catch-all's locale wiring.
-const i18n = data.config.i18n;
-const localeMeta = i18n
-  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
-  : null;
-const dir = localeMeta?.dir ?? "ltr";
-const htmlLang = i18n ? i18n.defaultLocale : "en";
-
 // The page chrome (h1, title, description) comes from the same translatable
 // \`changelog\` group as the reveal button; optional chaining tolerates a
 // not-yet-regenerated data snapshot from before these keys existed.

package/src/audit/agent.ts

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+
+import { join } from "pathe";
+
+import { reportJson } from "./report.ts";
+import type { AuditResult } from "./run.ts";
+
+/** A coding agent CLI the audit can hand its findings to (`--claude`, `--codex`). */
+export interface AgentCli {
+  /** The executable to look up on PATH. */
+  bin: string;
+  /** How to install it, shown when the executable is missing. */
+  install: string;
+  /** Display name for messages. */
+  name: string;
+}
+
+export type AgentKind = "claude" | "codex";
+
+export const AGENTS: Record<AgentKind, AgentCli> = {
+  claude: {
+    bin: "claude",
+    install: "npm install -g @anthropic-ai/claude-code",
+    name: "Claude Code",
+  },
+  codex: {
+    bin: "codex",
+    install: "npm install -g @openai/codex",
+    name: "Codex",
+  },
+};
+
+/**
+ * Write the full JSON report where the agent can read it. A file rather than
+ * inline prompt text: a large site's report can exceed the platform's argv
+ * limit, and the JSON already carries every finding untruncated — the terminal
+ * report previews three pages per check, the file never does.
+ */
+export const writeAgentReport = async (
+  result: AuditResult,
+  root: string
+): Promise<string> => {
+  const dir = await mkdtemp(join(tmpdir(), "blume-audit-"));
+  const path = join(dir, "report.json");
+  await writeFile(path, reportJson(result, root));
+  return path;
+};
+
+/** The handoff prompt: where the report is, how to read it, and the ground rules. */
+export const fixPrompt = (reportPath: string): string =>
+  `Fix the issues found by \`blume audit\` in this project.
+
+The full audit report is at ${reportPath}. It is JSON: each entry in \`diagnostics\` is one finding, with the check \`code\`, a \`message\` explaining what is wrong, the affected page \`url\`, the source \`file\` to edit (relative to the current directory, with a \`line\` when the finding points at a specific front matter key), and a \`suggestion\` describing the fix.
+
+Work through every finding:
+1. Read the report and group the findings by \`file\`.
+2. Apply each finding's \`suggestion\` by editing the named source file — most fixes are front matter edits at the cited line.
+3. Never fix a finding by deleting a page, removing content, or hiding it from the audit; if a finding genuinely needs a human decision, leave it and say so in your summary.
+
+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> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { shell, 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.
+ *
+ * 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.
+ */
+export const launchAgent = async (
+  bin: string,
+  prompt: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<number> => {
+  if (platform !== "win32") {
+    return await spawnAgent(bin, [prompt], false);
+  }
+  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
+  );
+};