blume 2.0.0 → 2.0.2

package/src/registry/eject.ts

@@ -23,6 +23,10 @@ import {
   detectNeedsReact,
   detectUsesMath,
   languageIconCssFor,
+  PLAYGROUND_PROXY_ENTRY,
+  playgroundProxyPattern,
+  proxyAllowlistWarnings,
+  specOrigins,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
@@ -32,6 +36,7 @@ import {
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
+  contentAssetsEndpointTemplate,
   contentConfigTemplate,
   exampleMapTemplate,
   exampleSlug,
@@ -43,6 +48,7 @@ import {
   mixedbreadSearchEndpointTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
+  playgroundProxyTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
   runtimeDependencies,
@@ -51,6 +57,7 @@ import {
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
 } from "../astro/templates.ts";
+import { collectContentAssets } from "../core/content-assets.ts";
 import { buildIncludeGraph } from "../core/includes.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
@@ -62,7 +69,10 @@ import {
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import type { OpenApiData } from "../openapi/model.ts";
-import { hasScalarReferences } from "../openapi/references.ts";
+import {
+  hasScalarReferences,
+  needsPlaygroundProxy,
+} from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
@@ -116,16 +126,16 @@ const ejectOpenApiData = (project: BlumeProject): OpenApiData => {
 };
 
 /**
- * The Ask AI endpoint plus, unless the backend runs its own retrieval (Inkeep),
- * its grounding snapshot. Empty when Ask AI is disabled.
+ * The assistant endpoint plus, unless the backend runs its own retrieval (Inkeep),
+ * its grounding snapshot. Empty when the assistant is disabled.
  */
 const askFiles = async (
   project: BlumeProject,
   srcDir: string,
   genDir: string
 ): Promise<{ content: string; path: string }[]> => {
-  const { ask } = project.config.ai;
-  if (!(ask?.enabled && !ask.endpoint)) {
+  const { assistant } = project.config.ai;
+  if (!(assistant?.enabled && !assistant.endpoint)) {
     const endpointPath = join(srcDir, "pages", "api", "ask.ts");
     if (existsSync(endpointPath)) {
       const content = await readFile(endpointPath, "utf-8");
@@ -136,13 +146,13 @@ const askFiles = async (
     await rm(join(genDir, "ask-data.json"), { force: true });
     return [];
   }
-  const backend = resolveAskBackend(ask.provider);
+  const backend = resolveAskBackend(assistant.provider);
   const files = [
     {
       content: askEndpointTemplate(backend, {
-        cors: ask.cors,
-        instructions: ask.instructions,
-        retrieval: ask.retrieval,
+        cors: assistant.cors,
+        instructions: assistant.instructions,
+        retrieval: assistant.retrieval,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
@@ -190,6 +200,43 @@ const mcpDiscoveryPages = (
       ]
     : [];
 
+/**
+ * The playground's built-in CORS proxy route (`playground: { proxy: true }`),
+ * mirroring `planPlaygroundProxy` in generate.ts: injected like the MCP
+ * discovery routes, because Astro treats a `_`-prefixed page file as private,
+ * and mounted under `basePath` at the URL the playground sends to. Empty when
+ * no reference routes its playground through it.
+ */
+const playgroundProxyPages = (
+  config: BlumeProject["config"]
+): { entrypoint: string; pattern: string }[] =>
+  needsPlaygroundProxy(config)
+    ? [
+        {
+          entrypoint: toPosix(join("src", PLAYGROUND_PROXY_ENTRY)),
+          pattern: playgroundProxyPattern(config),
+        },
+      ]
+    : [];
+
+/**
+ * The proxy endpoint behind {@link playgroundProxyPages}, with the origin
+ * allowlist baked in from the same parsed specs the reference pages render.
+ */
+const playgroundProxyFiles = (
+  config: BlumeProject["config"],
+  openApiData: OpenApiData,
+  srcDir: string
+): { content: string; path: string }[] =>
+  needsPlaygroundProxy(config)
+    ? [
+        {
+          content: playgroundProxyTemplate(specOrigins(openApiData)),
+          path: join(srcDir, PLAYGROUND_PROXY_ENTRY),
+        },
+      ]
+    : [];
+
 /**
  * The MCP data snapshot, server endpoint, and `.well-known` discovery
  * documents, mirroring `writeMcpFiles` in generate.ts. Empty when the server
@@ -265,6 +312,40 @@ const changelogFiles = (
   ];
 };
 
+/**
+ * The colocated-image map and the `/blume-assets/[...asset]` endpoint that
+ * serves it, mirroring generate.ts: the ejected raw Markdown points
+ * `![x](./diagram.png)` at `/blume-assets/content/…`, and the config aliases
+ * `blume:content-assets` to the map. Each original's path is written relative
+ * to the project root (the directory `astro dev`/`astro build` run from), so
+ * the ejected app builds from any checkout. Remote-source images need no
+ * endpoint: eject copies them into the project's own `public/blume-assets`.
+ */
+const contentAssetFiles = async (
+  project: BlumeProject,
+  root: string,
+  srcDir: string,
+  genDir: string
+): Promise<{ content: string; path: string }[]> => {
+  const assets = await collectContentAssets(project);
+  const portable = Object.fromEntries(
+    Object.entries(assets).map(([param, abs]) => [
+      param,
+      toPosix(relative(root, abs)),
+    ])
+  );
+  return [
+    {
+      content: `${JSON.stringify(portable)}\n`,
+      path: join(genDir, "content-assets.json"),
+    },
+    {
+      content: contentAssetsEndpointTemplate(null),
+      path: join(srcDir, "pages", "blume-assets", "[...asset].ts"),
+    },
+  ];
+};
+
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
 /**
  * Read a user stylesheet that eject inlines into a generated entry under
@@ -309,29 +390,33 @@ const examplesPreviewFiles = (
 
 /**
  * The packages the ejected app imports by bare name: Astro, Tailwind's Vite
- * plugin, `blume` itself, the integrations the config wires in, whatever the
- * configured adapters declare, and React when islands, examples, or Ask AI
- * render with it (Blume ships React, so projects rarely list it). They have
- * to be the project's own dependencies after eject — under a strict linker
- * such as pnpm nothing else makes them resolvable, and `astro build` fails.
- * The hidden runtime reaches the same packages through its `node_modules`
- * junction into Blume's own, so only eject declares the ones its generated
- * files import directly: the AI SDK the Ask AI route streams through (unless
- * `ai.ask.endpoint` points elsewhere, when no route is written) and the EPUB
- * generator's browser bundle `features.ts` loads.
+ * plugin, Tailwind and its typography plugin (which the generated `app.css`
+ * and `examples.css` import by name), `blume` itself, the integrations the
+ * config wires in, whatever the configured adapters declare, and React when
+ * islands, examples, or the assistant render with it (Blume ships React, so
+ * projects rarely list it). They have to be the project's own dependencies
+ * after eject — under a strict linker such as pnpm nothing else makes them
+ * resolvable, and `astro build` fails. The hidden runtime reaches the same
+ * packages through its `node_modules` junction into Blume's own, so only
+ * eject declares the ones its generated files import directly: the AI SDK the
+ * assistant route streams through (unless `ai.assistant.endpoint` points
+ * elsewhere, when no route is written) and the EPUB generator's browser bundle
+ * `features.ts` loads (only named there when `export.epub` is on).
  */
 const ejectDependencies = (
   options: Parameters<typeof runtimeDependencies>[0]
 ): string[] => {
-  const { ask } = options.config.ai;
+  const { assistant } = options.config.ai;
   return [
     ...new Set([
       "astro",
       "@tailwindcss/vite",
+      "tailwindcss",
+      "@tailwindcss/typography",
       "blume",
       ...runtimeDependencies(options),
       ...(options.needsReact ? ["react", "react-dom"] : []),
-      ...(ask?.enabled && !ask.endpoint ? ["ai"] : []),
+      ...(assistant?.enabled && !assistant.endpoint ? ["ai"] : []),
       ...(options.config.export.epub ? ["epub-gen-memory"] : []),
     ]),
   ];
@@ -364,7 +449,7 @@ export const eject = async (
 
   const srcDir = join(root, "src");
   const genDir = join(srcDir, "generated");
-  const askEnabled = config.ai.ask?.enabled ?? false;
+  const assistantEnabled = config.ai.assistant?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
 
@@ -402,13 +487,14 @@ export const eject = async (
     relativeTo: genDir,
   });
   // Island/example/override frameworks drive which Astro renderers the ejected
-  // config wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
+  // config wires in; React also switches on for project `.tsx`/`.jsx` and the assistant.
   const frameworks = new Set<string>([
     ...islands.islands.map((island) => island.framework),
     ...examples.examples.map((example) => example.framework),
     ...slotPlan.frameworks,
   ]);
-  const needsReact = needsReactRaw || askEnabled || frameworks.has("react");
+  const needsReact =
+    needsReactRaw || assistantEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
 
@@ -438,7 +524,9 @@ export const eject = async (
       pattern: page.pattern,
     })),
     ...mcpDiscoveryPages(project, pages),
+    ...playgroundProxyPages(config),
   ];
+  const openApiData = ejectOpenApiData(project);
 
   // Non-filesystem sources eject their materialized MDX into `<root>/blume-staged`
   // (a dedicated dir so it never clashes with a content root literally named
@@ -550,11 +638,11 @@ export const eject = async (
     // The header's Ask trigger behind the `blume:ask` alias. Always written — it
     // renders nothing when Ask is off — so the alias always resolves.
     {
-      content: askComponentTemplate(askEnabled),
+      content: askComponentTemplate(assistantEnabled),
       path: join(genDir, "Ask.astro"),
     },
     {
-      content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
+      content: `${JSON.stringify(openApiData)}\n`,
       path: join(genDir, "openapi.json"),
     },
     {
@@ -580,30 +668,38 @@ export const eject = async (
     },
   ];
 
-  if (askEnabled) {
+  files.push(...(await contentAssetFiles(project, root, srcDir, genDir)));
+
+  if (assistantEnabled) {
     files.push(...(await askFiles(project, srcDir, genDir)));
   }
 
+  // The `/changelog` index, mirrored from the generated runtime (`[]` when
+  // the project has no changelog). The OG endpoint below adds its card.
+  const changelog = changelogFiles(project, pages, srcDir, {
+    exportEpub,
+    exportPdf,
+    needsReact,
+    staged: hasStaged,
+  });
+
   if (config.seo.og.enabled) {
     files.push({
       content: ogEndpointTemplate(
         customOgRoutes(pages, config.title, config.seo.og.titles),
-        { pageDescriptions: config.seo.og.description !== false }
+        { pageDescriptions: config.seo.og.description !== false },
+        changelog.length > 0
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }
 
-  // The hosted MCP server and the `/changelog` index, mirrored from the
-  // generated runtime (each helper returns `[]` when its feature is off).
+  // The hosted MCP server and the playground's built-in proxy, mirrored from
+  // the generated runtime (`[]` when each is off).
   files.push(
     ...(await mcpFiles(project, pages, srcDir, genDir)),
-    ...changelogFiles(project, pages, srcDir, {
-      exportEpub,
-      exportPdf,
-      needsReact,
-      staged: hasStaged,
-    })
+    ...changelog,
+    ...playgroundProxyFiles(config, openApiData, srcDir)
   );
 
   // Default 404 page, unless the project already owns `/404` (a custom
@@ -672,7 +768,9 @@ export const eject = async (
   // the ejected app keeps its reference routes — including the warnings (a
   // missing spec file, a route collision), which the caller surfaces exactly
   // like the generated-runtime path does.
-  const warnings: string[] = [];
+  // A proxied spec with no origin to allow gets the generated runtime's
+  // diagnostic too.
+  const warnings: string[] = proxyAllowlistWarnings(config, openApiData);
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/search/documents.ts

@@ -16,6 +16,7 @@ import { applyAudienceVisibility } from "../ai/visibility.ts";
 import type { VisibilityAudience } from "../ai/visibility.ts";
 import matter from "../core/frontmatter.ts";
 import { parseHeadingMarkers } from "../core/heading-markers.ts";
+import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { contentIndexable } from "../core/manifest.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { HTML_COMMENT } from "../core/sources/normalize.ts";
@@ -149,7 +150,7 @@ const parseMarkdown = (
   format === "mdx" ? parseMdx(markdown) : markdownToMdast(markdown, MD_PARSE);
 
 // Fenced code is excluded from the plain index by default (ranking noise) —
-// the "markdown" extraction keeps it for Ask AI grounding. Code-heavy docs opt
+// the "markdown" extraction keeps it for assistant grounding. Code-heavy docs opt
 // in via `search.indexing.includeCodeBlocks`, which indexes the fence body and
 // its rendered title (```ts blume.config.ts) but never the fence markers,
 // language, or other meta keywords.
@@ -383,7 +384,7 @@ const pageBody = async (
  *
  * `content` selects the extraction: `"plain"` (default) strips Markdown to bare
  * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
- * headings — for Ask AI grounding, where fenced examples are often the answer
+ * headings — for assistant grounding, where fenced examples are often the answer
  * and stripping them makes the model unable to cite content the docs do contain.
  * The `"markdown"` body is agent-facing, so components are downleveled with the
  * same serializers the `.md` mirror, llms-full.txt and MCP `get_page` use: a
@@ -447,6 +448,26 @@ export const buildSearchDocuments = async (
   // otherwise.
   const components = projectComponentSerializers(project);
 
+  // A page in no sidebar group falls under the "Docs" section, in its own
+  // language: the label is a UI string, resolved once per locale.
+  const { i18n } = project.config;
+  const docsSections = new Map<string, string>();
+  const docsSection = (locale: string): string => {
+    let label = docsSections.get(locale);
+    if (label === undefined) {
+      label = (
+        i18n
+          ? resolveUIStrings(locale, {
+              defaultLocale: i18n.defaultLocale,
+              overrides: i18n.ui,
+            })
+          : EN_UI
+      ).search.docs;
+      docsSections.set(locale, label);
+    }
+    return label;
+  };
+
   return await Promise.all(
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
@@ -461,7 +482,7 @@ export const buildSearchDocuments = async (
         description: page?.description ?? "",
         locale: route.locale,
         route: route.path,
-        section: crumb?.section || "Docs",
+        section: crumb?.section || docsSection(route.locale),
         tags: tags && tags.length > 0 ? tags : undefined,
         title: route.title,
         version: route.version,

package/src/search/orama-index.ts

@@ -298,7 +298,7 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
 
 /**
  * Build an in-memory Orama full-text index from search documents. Shared by the
- * Orama client loader (browser), the MCP server, and Ask AI grounding (Node),
+ * Orama client loader (browser), the MCP server, and assistant grounding (Node),
  * so ranking is identical wherever docs are queried. `locale` — the site's
  * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for every
  * non-Latin script, all of which Orama's default tokenizer reduces to zero

package/src/search/sync/algolia.ts

@@ -7,6 +7,19 @@ import type { SearchRecord } from "../documents.ts";
 /** The adapter options the sync reads (the public `apiKey` is never used). */
 export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
 
+/**
+ * The record attributes the search dialog filters on (`facetFilters` on
+ * `locale:<code>` and `version:<id>`). In Algolia a facet filter on an
+ * attribute the index doesn't declare for faceting matches nothing — an i18n
+ * or versioned site would get no hits — so the sync declares them,
+ * filter-only.
+ */
+const FILTER_ATTRIBUTES = ["locale", "version"] as const;
+
+/** A faceting declaration's attribute: `filterOnly(locale)` → `locale`. */
+const facetAttribute = (declaration: string): string =>
+  declaration.replace(/^\w+\((?<name>.*)\)$/u, "$<name>");
+
 /**
  * Upload the search records to Algolia. Uses the admin key from
  * `ALGOLIA_ADMIN_API_KEY` (never the adapter options, which hold only the
@@ -14,7 +27,9 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked.
+ * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
+ * the site declared itself, so the dialog's locale and version filters match.
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
@@ -28,8 +43,27 @@ export const syncAlgolia = async (
   // `core/node-require.ts`).
   const { algoliasearch }: typeof AlgoliaSdk = nodeRequire("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
+  const { indexName } = config;
   await client.replaceAllObjects({
-    indexName: config.indexName,
+    indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });
+  const { attributesForFaceting = [] } = await client.getSettings({
+    indexName,
+  });
+  const declared = new Set(attributesForFaceting.map(facetAttribute));
+  const missing = FILTER_ATTRIBUTES.filter((name) => !declared.has(name));
+  if (missing.length === 0) {
+    return;
+  }
+  const { taskID } = await client.setSettings({
+    indexName,
+    indexSettings: {
+      attributesForFaceting: [
+        ...attributesForFaceting,
+        ...missing.map((name) => `filterOnly(${name})`),
+      ],
+    },
+  });
+  await client.waitForTask({ indexName, taskID });
 };

package/src/sources/registry.ts

@@ -165,6 +165,11 @@ const sourceEntrySchema = z
   .custom<SourceAdapterInput>(
     (value) => isObjectLike(value) && "kind" in value,
     {
+      // `z.custom` marks its failure as aborting by default, which makes Zod
+      // skip even the `content` refinement that opts in to running after a
+      // failed field (the shorthand beside `sources`). The pipe below stops
+      // at this entry either way.
+      abort: false,
       error: (issue) => {
         const legacy = legacyEntrySchema.safeParse(issue.input);
         return entryHint(legacy.success ? legacy.data.type : undefined);

package/src/theme/entry.ts

@@ -268,7 +268,7 @@ ${THEME_MAPPING}
   @apply block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground;
 }
 @utility blume-nav-drill {
-  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted;
+  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-start font-medium text-foreground text-sm transition-colors hover:bg-muted;
 }
 @utility blume-nav-summary {
   @apply flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden;
@@ -884,11 +884,18 @@ pre:has(.line.focused):hover .line:not(.focused) {
 }
 
 /* Print / "Save as PDF" (the page-actions Export → PDF runs window.print()).
-   Strip the surrounding chrome so the printout is just the article. */
+   Strip the surrounding chrome so the printout is just the article. Scoped to
+   the chrome itself, never bare \`header\`/\`aside\`: content renders those too
+   (every Callout and Panel is an <aside>, every changelog Update has a
+   <header>), and they belong in the printout. \`body > header\` keeps a
+   \`layout.Header\` override out as well. */
 @media print {
   [data-blume-banner],
-  header,
-  aside,
+  [data-blume-header],
+  body > header,
+  [data-blume-nav-drawer],
+  [data-blume-toc],
+  [data-blume-assistant-panel],
   [data-blume-page-actions],
   #blume-content > nav,
   #blume-content > details {

package/src/translate/agents.ts

@@ -1,5 +1,5 @@
 import type { AgentKind } from "../audit/agent.ts";
-import { DISALLOWED_TOOLS } from "../eval/agents.ts";
+import { CODEX_LOCKDOWN, DISALLOWED_TOOLS } from "../eval/agents.ts";
 
 /**
  * argv builders for the translator role. The subprocess machinery
@@ -28,6 +28,10 @@ const claudeArgs = (): string[] => [
   "1",
 ];
 
+// `--sandbox read-only` alone still lets codex's shell read any file the user
+// can, and the source page being translated is untrusted input (a remote
+// contributor's prose), so the translator gets the same lockdown as an eval
+// run: no shell, exec, or local-image tool, and no inherited environment.
 const codexArgs = (lastMessagePath: string): string[] => [
   "exec",
   "--skip-git-repo-check",
@@ -35,6 +39,7 @@ const codexArgs = (lastMessagePath: string): string[] => [
   "--ephemeral",
   "--sandbox",
   "read-only",
+  ...CODEX_LOCKDOWN,
   "--output-last-message",
   lastMessagePath,
   "-",

package/src/translate/ledger.ts

@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "pathe";
 import { z } from "zod";
 
+import { BlumeError } from "../core/diagnostics.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
 
 /**
@@ -39,21 +40,34 @@ export const emptyLedger = (): TranslationLedger => ({
  * every locale's stamp. sha256-16 like the audit snapshot's content hash.
  * Kept as its own function rather than sharing core's `hashText`: ledger
  * stamps persist in user repos, so this hash must never change shape when an
- * ephemeral cache hash does.
+ * ephemeral cache hash does. CRLF line endings are normalized to LF first, so
+ * a Windows checkout (`core.autocrlf`) hashes the same as everyone else's —
+ * LF text hashes exactly as it always has.
  */
 export const hashSource = (text: string): string =>
-  createHash("sha256").update(text).digest("hex").slice(0, 16);
+  createHash("sha256")
+    .update(text.replaceAll("\r\n", "\n"))
+    .digest("hex")
+    .slice(0, 16);
+
+/** A git merge-conflict marker line: `<<<<<<< ours`, `=======`, `>>>>>>> theirs`. */
+const CONFLICT_MARKER = /^(?:<{7}|={7}|>{7})(?:[ \r]|$)/mu;
 
 /**
  * Read the ledger at `root`, tolerantly: a missing file, unparseable JSON, or
  * an unknown shape/version all resolve to an empty ledger rather than an error
  * (same posture as the dev lock's `parseLock`) — the worst outcome of a
  * corrupt ledger is retranslating files that were already up to date.
+ *
+ * Unresolved merge-conflict markers are the exception, and an error: read as
+ * empty, every existing translation would be adopted as current, so
+ * `--check` would pass over translations that are out of date.
  */
 export const readLedger = async (root: string): Promise<TranslationLedger> => {
+  const path = join(root, LEDGER_FILE);
   let raw: string;
   try {
-    raw = await readFile(join(root, LEDGER_FILE), "utf-8");
+    raw = await readFile(path, "utf-8");
   } catch {
     return emptyLedger();
   }
@@ -61,6 +75,15 @@ export const readLedger = async (root: string): Promise<TranslationLedger> => {
   try {
     data = JSON.parse(raw);
   } catch {
+    if (CONFLICT_MARKER.test(raw)) {
+      throw new BlumeError({
+        code: "BLUME_TRANSLATE_LEDGER_CONFLICT",
+        file: path,
+        message: `${LEDGER_FILE} has unresolved merge-conflict markers, so it can't say which translations are current.`,
+        severity: "error",
+        suggestion: `Resolve the merge conflict in ${LEDGER_FILE}, then rerun.`,
+      });
+    }
     return emptyLedger();
   }
   const parsed = ledgerSchema.safeParse(data);

package/src/translate/meta.ts

@@ -57,7 +57,9 @@ export const metaTargetPath = (
 /**
  * Discover the default-locale `meta.{ts,js,mjs}` files whose titles a
  * translation run covers. Skips (in order): non-`dir` i18n projects entirely,
- * files inside a configured locale directory (those ARE translations),
+ * files inside a configured locale directory (those ARE translations), files
+ * inside an archived-version snapshot (frozen, with their own translations —
+ * the same folders the navigation's meta lookup hoists as versions),
  * factory-form modules (a warning — the generator can't re-emit a function),
  * modules that fail meta validation (the scan already errors on those), and
  * modules with no `title` (nothing to translate).
@@ -74,6 +76,9 @@ export const discoverTranslatableMeta = async (
       locale.code === i18n.defaultLocale ? [] : [locale.code.toLowerCase()]
     )
   );
+  const versionDirs = new Set(
+    project.config.versions?.archived.map((version) => version.id)
+  );
 
   const load = createModuleLoader();
   const metas: TranslatableMeta[] = [];
@@ -92,8 +97,11 @@ export const discoverTranslatableMeta = async (
     });
     for (const file of files.toSorted()) {
       const dir = relative(contentRoot, dirname(file));
-      const first = dir.split("/")[0]?.toLowerCase();
-      if (first && localeDirs.has(first)) {
+      const [head] = dir.split("/");
+      if (
+        head &&
+        (localeDirs.has(head.toLowerCase()) || versionDirs.has(head))
+      ) {
         continue;
       }
       // oxlint-disable-next-line no-await-in-loop -- sequential, ordered discovery

package/src/translate/report.ts

@@ -185,7 +185,7 @@ const driftDiagnostics = (workList: TranslateWorkList): Diagnostic[] =>
         : `The "${row.locale}" translation of ${row.sourceRel} is stale: its source changed since it was translated.`,
     severity: "error",
     suggestion:
-      "Run `blume translate --claude` (or `--codex`) to bring the translations up to date.",
+      "Run `blume translate --codex` (or `--claude`) to bring the translations up to date.",
   }));
 
 /** One line per missing/stale pair, plus dim lines for untracked adoptions. */