blume 2.0.1 → 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";
@@ -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,16 +390,18 @@ 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 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.
+ * 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]
@@ -328,6 +411,8 @@ const ejectDependencies = (
     ...new Set([
       "astro",
       "@tailwindcss/vite",
+      "tailwindcss",
+      "@tailwindcss/typography",
       "blume",
       ...runtimeDependencies(options),
       ...(options.needsReact ? ["react", "react-dom"] : []),
@@ -439,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
@@ -555,7 +642,7 @@ export const eject = async (
       path: join(genDir, "Ask.astro"),
     },
     {
-      content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
+      content: `${JSON.stringify(openApiData)}\n`,
       path: join(genDir, "openapi.json"),
     },
     {
@@ -581,30 +668,38 @@ export const eject = async (
     },
   ];
 
+  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
@@ -673,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";
@@ -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/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/run.ts

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 
 import pLimit from "p-limit";
 import pMap from "p-map";
-import { join } from "pathe";
+import { dirname, join } from "pathe";
 
 import { AGENTS } from "../audit/agent.ts";
 import type { AgentKind } from "../audit/agent.ts";
@@ -18,6 +18,7 @@ import { DEFAULT_TRANSLATE_TIMEOUT_MS, translateAgentArgs } from "./agents.ts";
 import { hashSource, stampLedger } from "./ledger.ts";
 import type { TranslationLedger } from "./ledger.ts";
 import { generateMetaModule } from "./meta.ts";
+import type { TranslatableMeta } from "./meta.ts";
 import { metaPrompt, pagePrompt } from "./prompts.ts";
 import { parseMetaTitles, validateTranslation } from "./validate.ts";
 import type {
@@ -88,8 +89,13 @@ interface RunContext {
   timeoutMs: number;
 }
 
-/** The root directory's key in a meta-titles prompt (an empty key is opaque). */
-const metaDirKey = (dir: string): string => (dir === "" ? "." : dir);
+/**
+ * A meta file's key in a meta-titles prompt: its directory relative to the
+ * project root. The content-root-relative `dir` isn't unique — two
+ * filesystem sources can both have a `guides/` folder — and colliding keys
+ * would hand both folders one translation.
+ */
+const metaKey = (meta: TranslatableMeta): string => dirname(meta.sourceRel);
 
 /**
  * One headless agent call. A missing executable rejects with ENOENT on every
@@ -183,7 +189,7 @@ const runMetaItem = async (
   });
 
   const titles = Object.fromEntries(
-    item.entries.map((entry) => [metaDirKey(entry.meta.dir), entry.meta.title])
+    item.entries.map((entry) => [metaKey(entry.meta), entry.meta.title])
   );
   // SAFETY: `targets` maps every configured locale, and work items only carry
   // configured locale codes.
@@ -199,7 +205,7 @@ const runMetaItem = async (
 
   const parsed = parseMetaTitles(output.text, Object.keys(titles));
   for (const entry of item.entries) {
-    const translated = parsed.titles[metaDirKey(entry.meta.dir)];
+    const translated = parsed.titles[metaKey(entry.meta)];
     if (translated === undefined) {
       continue;
     }

package/src/translate/validate.ts

@@ -102,7 +102,16 @@ export const validateTranslation = (
   sourceText: string,
   agentText: string
 ): ValidationResult => {
-  const candidate = stripOuterFence(agentText);
+  // Only a fence the agent added is stripped. A source that is itself one
+  // code block (a frontmatter-less partial holding a single bash block)
+  // starts and ends with its own fence, which the translation must keep — so
+  // for such a source the reply loses its outer fence only when it has more
+  // fence lines than the source.
+  const sourceIsFenced = stripOuterFence(sourceText) !== sourceText.trim();
+  const candidate =
+    sourceIsFenced && countFenceLines(agentText) <= countFenceLines(sourceText)
+      ? agentText.trim()
+      : stripOuterFence(agentText);
   if (candidate === "") {
     return { ok: false, reason: "agent returned empty output" };
   }

package/src/translate/work-list.ts

@@ -1,9 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import { dirname, extname, join, relative } from "pathe";
 
 import { localeCodes, localeTargetPath } from "../core/i18n.ts";
+import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic, PageRecord } from "../core/types.ts";
 import { hashSource } from "./ledger.ts";
@@ -84,6 +85,36 @@ export interface TranslateWorkList {
 
 const PAGE_EXTENSIONS = new Set([".md", ".mdx"]);
 
+/**
+ * The names in each content root, read once per root: a locale folder authored
+ * in another casing (`pt-br/` for `pt-BR`) is where `localeTargetPath` puts
+ * that locale's translations.
+ */
+const rootFolders = (): ((contentRoot: string) => string[]) => {
+  const read = new Map<string, string[]>();
+  return (contentRoot) => {
+    const cached = read.get(contentRoot);
+    if (cached) {
+      return cached;
+    }
+    const names = readdirSync(contentRoot);
+    read.set(contentRoot, names);
+    return names;
+  };
+};
+
+/**
+ * Scan the project for a translation run: drafts included. A production
+ * (`build`) scan drops them, so a hand-written translation marked
+ * `draft: true` would look missing and be overwritten, and a source page
+ * drafted for a while would lose its ledger stamps — its outdated
+ * translations then reading as current once it's published again. A dev scan
+ * keeps drafts and differs only in reusing cached remote content, which
+ * translation never reads.
+ */
+export const scanForTranslation = (root: string): Promise<BlumeProject> =>
+  scanProject(root, { mode: "dev" });
+
 /**
  * The translatable page universe: filesystem-backed default-locale pages.
  * Remote/staged sources have no writable path; fallback records are padding;
@@ -201,6 +232,7 @@ const partialWorkItems = async (
       page.sourcePath ? [page.sourcePath] : []
     )
   );
+  const folders = rootFolders();
   const partials = new Map<string, string>();
   for (const { page, contentRoot } of universe) {
     for (const partial of page.includes ?? []) {
@@ -220,7 +252,7 @@ const partialWorkItems = async (
     for (const locale of targetLocales) {
       const targetPath = join(
         contentRoot,
-        localeTargetPath(contentRel, ext, locale, i18n)
+        localeTargetPath(contentRel, ext, locale, i18n, folders(contentRoot))
       );
       const item = (status: WorkStatus): PageWorkItem => {
         const partialItem: PageWorkItem = {
@@ -291,6 +323,7 @@ export const computeWorkList = async (
   let upToDate = 0;
 
   const universe = translatablePages(project, i18n);
+  const folders = rootFolders();
 
   for (const { page, contentRoot, ext, sourcePath } of universe) {
     const sourceRel = relative(root, sourcePath);
@@ -302,7 +335,7 @@ export const computeWorkList = async (
     for (const locale of targetLocales) {
       const targetPath = join(
         contentRoot,
-        localeTargetPath(contentRel, ext, locale, i18n)
+        localeTargetPath(contentRel, ext, locale, i18n, folders(contentRoot))
       );
       const item = (status: WorkStatus): PageWorkItem => ({
         kind: "page",