failproofai 0.0.14-beta.1 → 0.0.14

package/lib/entry-keys.ts

@@ -0,0 +1,36 @@
+/**
+ * Stable per-entry identity for the log viewer.
+ *
+ * Deliberately standalone and dependency-free: `lib/log-entries.ts` reaches
+ * fs/promises through its project-resolution imports, so a *value* import of
+ * it from a client component drags node:fs into the browser bundle and the
+ * session page 500s. Client code may only import types from there.
+ */
+import type { LogEntry } from "./log-entries";
+
+/**
+ * Assigns every entry a unique, render-stable identity.
+ *
+ * Not every CLI writes a per-record `uuid` — Codex, Copilot, Cursor and Pi
+ * transcripts have none, so `baseEntry` leaves it "". Keying rows off
+ * `uuid || timestamp` therefore collapses to the timestamp, which those CLIs
+ * reuse freely (one 771-record Codex session: 93 timestamps shared by 2-5
+ * records each). Duplicate React keys break reconciliation, and in the
+ * virtualized log list that strands orphaned DOM nodes stacked on top of live
+ * rows — they keep their old transform and never recover (#292 follow-up).
+ *
+ * Collisions are disambiguated by occurrence order, so keys stay stable for as
+ * long as the parsed entry list is — which is what React and the virtualizer's
+ * measurement cache both require.
+ */
+export function buildEntryKeys(entries: LogEntry[]): Map<LogEntry, string> {
+  const keys = new Map<LogEntry, string>();
+  const seen = new Map<string, number>();
+  for (const entry of entries) {
+    const base = entry.uuid || `${entry._source}:${entry.timestamp}`;
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    keys.set(entry, n === 0 ? base : `${base}#${n}`);
+  }
+  return keys;
+}

package/lib/format-duration.ts

@@ -16,14 +16,28 @@ export function formatRelativeTime(ts: number): string {
 
 export function formatDuration(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
-  const seconds = ms / 1000;
-  if (seconds < 60) return `${seconds.toFixed(1)}s`;
-  const totalMinutes = Math.floor(seconds / 60);
-  if (totalMinutes >= 60) {
-    const hours = Math.floor(totalMinutes / 60);
-    const remainingMinutes = totalMinutes % 60;
-    return `${hours}h ${remainingMinutes}m`;
+
+  // Round to the precision the output will actually use, then bucket.
+  // Seconds are shown with one decimal place, so round to the nearest 0.1 s
+  // before deciding whether we have crossed into the minute range.
+  const deciseconds = Math.round(ms / 100);
+  if (deciseconds < 600) {
+    return `${(deciseconds / 10).toFixed(1)}s`;
+  }
+
+  // Minutes are shown with whole seconds, so round to the nearest second
+  // before splitting into minutes and seconds.
+  const totalSeconds = Math.round(ms / 1000);
+  if (totalSeconds < 3600) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${seconds}s`;
   }
-  const remainingSeconds = (seconds % 60).toFixed(0);
-  return `${totalMinutes}m ${remainingSeconds}s`;
+
+  // Hours are shown with whole minutes, so round to the nearest minute
+  // before splitting into hours and minutes.
+  const totalMinutes = Math.round(ms / 60000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return `${hours}h ${minutes}m`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.14-beta.1",
+  "version": "0.0.14",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -71,11 +71,11 @@
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.111.0",
+    "@anthropic-ai/sdk": "^0.112.4",
     "@mdx-js/mdx": "^3.1.1",
     "@tailwindcss/postcss": "^4.3.1",
     "@tanstack/react-virtual": "^3.14.3",
-    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/node": "26.1.1",
@@ -106,6 +106,7 @@
     "postcss": "8.5.14",
     "eslint-plugin-react-hooks": "7.0.1",
     "vite": "8.0.16",
-    "undici": "7.28.0"
+    "undici": "7.28.0",
+    "brace-expansion": "5.0.7"
   }
 }

package/scripts/translate-docs/cli.ts

@@ -419,6 +419,12 @@ async function main() {
   if (totalInput > 0) {
     console.log(`Total tokens: ${totalInput} input + ${totalOutput} output`);
   }
+  // Surface pages that needed a re-translation to pass validation, so a run
+  // that quietly retried does not read as a clean one in the job log.
+  const retried = translated.filter((r) => (r.attempts ?? 1) > 1);
+  if (retried.length > 0) {
+    console.log(`Retried: ${retried.length}`);
+  }
 
   if (errors.length > 0) {
     process.exit(1);

package/scripts/translate-docs/mdx-translator.ts

@@ -10,7 +10,8 @@ import {
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getLanguageByCode } from "./config";
-import { translateContent } from "./translator";
+import { translateValidated } from "./translator";
+import { findTranslationError } from "./validate-translation";
 import {
   readCache,
   writeCache,
@@ -193,10 +194,13 @@ export async function translateMdxPage(
     dryRun?: boolean;
     model?: string;
     cache?: TranslationCache;
+    /** Override the docs root. Tests point this at a fixture tree. */
+    docsDir?: string;
   } = {},
 ): Promise<TranslationResult> {
-  const relPath = relative(DOCS_DIR, sourcePath);
-  const outputPath = join(DOCS_DIR, lang, relPath);
+  const docsDir = options.docsDir ?? DOCS_DIR;
+  const relPath = relative(docsDir, sourcePath);
+  const outputPath = join(docsDir, lang, relPath);
   const sourceContent = readFileSync(sourcePath, "utf-8");
 
   const langConfig = getLanguageByCode(lang);
@@ -228,25 +232,31 @@ export async function translateMdxPage(
     };
   }
 
-  // Translate
-  const { translated, inputTokens, outputTokens } = await translateContent(
-    sourceContent,
-    lang,
-    langConfig.name,
-    options.model,
-  );
-
-  // Strip stray quote artifacts from JSX attribute values, drop any
-  // unmatched trailing code fence the model sometimes hallucinates, convert
-  // any HTML comments to MDX comments, then rewrite links.
-  const sanitized = convertHtmlComments(
-    stripStrayTrailingFence(sanitizeJsxAttributes(translated)),
-  );
-  const withLinks = rewriteInternalLinks(sanitized, lang);
+  // Translate and validate the exact bytes we will write. The render callback
+  // reproduces the historical sanitize + link-rewrite chain byte-for-byte
+  // (strip stray JSX-attribute quotes, drop an unmatched trailing fence,
+  // convert HTML comments to MDX, then add the language prefix to links), so
+  // the validated bytes ARE the written bytes and a pass here equals a pass in
+  // the deploy. On exhaustion translateValidated throws before we reach the
+  // write, so an invalid page is never written or cached.
+  const { rendered, inputTokens, outputTokens, attempts } =
+    await translateValidated({
+      source: sourceContent,
+      lang,
+      langName: langConfig.name,
+      model: options.model,
+      label: `${relPath} [${lang}]`,
+      render: (raw) =>
+        rewriteInternalLinks(
+          convertHtmlComments(stripStrayTrailingFence(sanitizeJsxAttributes(raw))),
+          lang,
+        ),
+      validate: (bytes) => findTranslationError(bytes, sourceContent),
+    });
 
   // Write output
   mkdirSync(dirname(outputPath), { recursive: true });
-  writeFileSync(outputPath, withLinks);
+  writeFileSync(outputPath, rendered);
 
   // Update cache — skip if caller manages the cache (batch write)
   if (!options.cache) {
@@ -269,6 +279,7 @@ export async function translateMdxPage(
     inputTokens,
     outputTokens,
     cached: false,
+    attempts,
   };
 }
 

package/scripts/translate-docs/readme-translator.ts

@@ -2,12 +2,13 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { LANGUAGES, getLanguageByCode } from "./config";
-import { translateContent } from "./translator";
+import { translateValidated } from "./translator";
 import {
   stripStrayTrailingFence,
   convertHtmlComments,
   sanitizeJsxAttributes,
 } from "./mdx-translator";
+import { findTranslationError } from "./validate-translation";
 import { readCache, writeCache, isCached, setCacheEntry } from "./cache";
 import type { TranslationResult, TranslationCache } from "./types";
 
@@ -90,15 +91,12 @@ export async function translateReadme(
     };
   }
 
-  // Translate
-  const { translated, inputTokens, outputTokens } = await translateContent(
-    sourceContent,
-    lang,
-    langConfig.name,
-    options.model,
-  );
-
-  // Build the final output with header
+  // Compute the wrapper (disclaimer, language selector, RTL <div>) up front so
+  // the render callback can assemble the FINAL bytes on every attempt. The
+  // assembled bytes — not the raw model output — are what gets validated: the
+  // swallowed-`</div>` class is introduced by the wrapper AFTER the model
+  // returns, and `mintlify validate` never sees the README at all, so this gate
+  // is the only thing standing between a broken README and the deploy.
   const disclaimer = langConfig.rtl
     ? `> **\u26a0\ufe0f** \u0647\u0630\u0647 \u062a\u0631\u062c\u0645\u0629 \u0622\u0644\u064a\u0629. \u0644\u0644\u0627\u0637\u0644\u0627\u0639 \u0639\u0644\u0649 \u0623\u062d\u062f\u062b \u0625\u0635\u062f\u0627\u0631\u060c \u0631\u0627\u062c\u0639 [English README](../../README.md).`
     : `> **\u26a0\ufe0f** This is an auto-generated translation. For the latest version, see the [English README](../../README.md). Community corrections welcome!`;
@@ -107,20 +105,31 @@ export async function translateReadme(
   const rtlOpen = langConfig.rtl ? `<div dir="rtl">\n\n` : "";
   const rtlClose = langConfig.rtl ? `\n\n</div>` : "";
 
-  // Run the same MDX sanitizers as translateMdxPage — the README emits JSX
-  // (the logo table), so its output has to satisfy Mintlify's MDX parser too:
-  // strip stray quote artifacts from JSX attributes, drop any unmatched
-  // trailing code fence the model hallucinates (which would swallow the RTL
-  // `</div>` wrapper), and convert HTML comments to MDX comments.
-  const cleaned = convertHtmlComments(
-    stripStrayTrailingFence(sanitizeJsxAttributes(translated)),
-  );
-
-  const output = `${disclaimer}\n\n${langSelector}\n\n---\n${rtlOpen}\n${cleaned}\n${rtlClose}`;
+  // Translate and validate the assembled bytes, re-translating on failure.
+  const { rendered, inputTokens, outputTokens, attempts } =
+    await translateValidated({
+      source: sourceContent,
+      lang,
+      langName: langConfig.name,
+      model: options.model,
+      label: `README.${lang}.md`,
+      render: (raw) => {
+        // Same MDX sanitizers as translateMdxPage — the README emits JSX (the
+        // logo table), so strip stray attribute quotes, drop any unmatched
+        // trailing code fence (which would swallow the RTL `</div>`), and
+        // convert HTML comments to MDX — then wrap in disclaimer + selector +
+        // RTL div.
+        const cleaned = convertHtmlComments(
+          stripStrayTrailingFence(sanitizeJsxAttributes(raw)),
+        );
+        return `${disclaimer}\n\n${langSelector}\n\n---\n${rtlOpen}\n${cleaned}\n${rtlClose}`;
+      },
+      validate: (bytes) => findTranslationError(bytes, sourceContent),
+    });
 
   // Write output
   mkdirSync(I18N_DIR, { recursive: true });
-  writeFileSync(outputPath, output);
+  writeFileSync(outputPath, rendered);
 
   // Update cache — skip if caller manages the cache (batch write)
   if (!options.cache) {
@@ -136,6 +145,7 @@ export async function translateReadme(
     inputTokens,
     outputTokens,
     cached: false,
+    attempts,
   };
 }
 

package/scripts/translate-docs/translator.ts

@@ -25,6 +25,25 @@ const MAX_TOKENS =
     ? parsedMaxTokens
     : 64000;
 
+// Maximum TOTAL validation attempts per page: 1 initial translation plus up to
+// MAX_ATTEMPTS-1 re-translations when the rendered output fails validation
+// (see translateValidated below). Distinct from the SDK transport budget
+// TRANSLATE_MAX_RETRIES (default 5, in getClient): that retries a single HTTP
+// request on a connection error; this re-translates a page whose *content*
+// failed the docs-build checks. They multiply — at most
+// MAX_ATTEMPTS x (1 + maxRetries) HTTP requests for one page in the worst case.
+// 3 collapses the observed per-page failure rate to negligible while costing
+// wall-clock (a serial retry inside one worker slot), not peak concurrency.
+// Override via TRANSLATE_MAX_ATTEMPTS (integer >= 1; 1 disables retries).
+const parsedMaxAttempts = Number.parseInt(
+  process.env.TRANSLATE_MAX_ATTEMPTS ?? "",
+  10,
+);
+const MAX_ATTEMPTS =
+  Number.isInteger(parsedMaxAttempts) && parsedMaxAttempts > 0
+    ? parsedMaxAttempts
+    : 3;
+
 function getClient(): Anthropic {
   if (!client) {
     // Default 5 retries (up from SDK default of 2) so transient
@@ -44,7 +63,7 @@ const SYSTEM_PROMPT = `You are a professional technical documentation translator
 
 1. **Preserve all code blocks exactly as-is** — never translate content inside backtick-fenced code blocks (\`\`\`...\`\`\`) or inline code (\`...\`).
 2. **Preserve MDX component syntax** — tags like <Card>, <CardGroup>, <CodeGroup>, <Steps>, <Step>, <Note>, <Tip>, <Tabs>, <Tab>, <Warning> must remain unchanged. Their attribute names (title, icon, href, cols) must remain in English. Only translate the text content of the \`title\` attribute and the text body between tags. **Never put an ASCII straight \`"\` inside a \`title="…"\` (or any JSX attribute value)** — it terminates the attribute and breaks MDX parsing. If the target language would normally wrap a word in quotation marks (e.g. German „…", Japanese 「…」), drop the inner quotes inside attribute values and rely on the surrounding tag for emphasis.
-3. **Preserve YAML frontmatter keys** — only translate the string values of \`title\` and \`description\`. Keep the \`icon\` value unchanged.
+3. **Preserve YAML frontmatter keys** — only translate the string values of \`title\` and \`description\`. Keep the \`icon\` value unchanged. Never rename, add, or drop a frontmatter key. The \`title\` and \`description\` values are wrapped in double quotes: **never put an unescaped ASCII \`"\` inside them** — it terminates the YAML string and breaks the frontmatter parse (exactly as an ASCII \`"\` breaks a JSX attribute in rule 2). If the source value contains an escaped quote (\`\\"\`), keep it escaped in the same form; if the target language would quote a phrase, use typographic quotes (e.g. „…", «…», 「…」) or rephrase to avoid the inner quote.
 4. **Preserve all URLs and paths** — never modify href values, image paths, or links.
 5. **Preserve Markdown structure** — headers (#, ##), lists (-, *), tables (|), bold (**), italic (*), links ([text](url)) must keep their Markdown formatting.
 6. **Preserve badge/shield URLs** — any [![...](https://img.shields.io/...)](url) pattern must remain completely unchanged.
@@ -65,11 +84,40 @@ ${DO_NOT_TRANSLATE.map((t) => `- ${t}`).join("\n")}
 
 Return ONLY the translated content. Do not add explanations, notes, or commentary.`;
 
+export interface RetryFeedback {
+  attempt: number;
+  maxAttempts: number;
+  /** The previous attempt's validation error — model-actionable text. */
+  error: string;
+}
+
+/**
+ * The repair note appended to the user turn on a retry. The failed attempt is
+ * NOT fed back as an assistant turn: a fresh re-translate keeps the input flat
+ * across attempts. Conversational repair would grow the input every attempt and
+ * push a large README toward the max_tokens ceiling on exactly the retry where
+ * a truncation would be worst — and the error is self-locating (it carries the
+ * caret excerpt / body snippet), so the model needs the note, not its own prior
+ * output, to fix the defect.
+ */
+function buildRetryFeedback(f: RetryFeedback): string {
+  return (
+    `[Retry ${f.attempt} of ${f.maxAttempts}. The source document above is unchanged.]\n\n` +
+    "Your previous translation of this document was REJECTED by the docs build " +
+    "and discarded. It failed validation with:\n\n" +
+    `${f.error}\n\n` +
+    "Translate the source again from the beginning and return ONLY the " +
+    "corrected translation — do not comment on this note. Do not reproduce that " +
+    "defect. Every rule above still applies."
+  );
+}
+
 export async function translateContent(
   content: string,
   targetLang: string,
   targetLangName: string,
   model: string = "claude-sonnet-4-6",
+  feedback?: RetryFeedback,
 ): Promise<{ translated: string; inputTokens: number; outputTokens: number }> {
   const anthropic = getClient();
 
@@ -81,16 +129,18 @@ export async function translateContent(
   // surfaces to the SDK as `APIConnectionError ("Connection error.")`.
   // `messages.stream(...).finalMessage()` returns the same Message shape
   // as `messages.create(...)`, so the rest of the pipeline is unchanged.
+  const base = `Translate the following documentation content into ${targetLangName} (${targetLang}).\n\n---\n\n${content}`;
+  // On a retry, append the repair note after the source in the SAME single user
+  // turn — no assistant turn is fed back, so the request stays flat-input.
+  const userContent = feedback
+    ? `${base}\n\n---\n\n${buildRetryFeedback(feedback)}`
+    : base;
+
   const response = await anthropic.messages.stream({
     model,
     max_tokens: MAX_TOKENS,
     system: [{ type: "text", text: SYSTEM_PROMPT, cache_control: { type: "ephemeral" } }],
-    messages: [
-      {
-        role: "user",
-        content: `Translate the following documentation content into ${targetLangName} (${targetLang}).\n\n---\n\n${content}`,
-      },
-    ],
+    messages: [{ role: "user", content: userContent }],
   }).finalMessage();
 
   // A truncated translation is worse than a failed one: the model stops
@@ -116,3 +166,88 @@ export async function translateContent(
     outputTokens: response.usage.output_tokens,
   };
 }
+
+/**
+ * Translate `source`, render it to the exact bytes that will be written, and
+ * validate those bytes — re-translating with the validation error fed back
+ * until it passes or MAX_ATTEMPTS is reached.
+ *
+ * The loop lives here, not in translateContent, because each caller renders
+ * different final bytes (the MDX pages add rewriteInternalLinks; the README
+ * wraps the body in a disclaimer + RTL `<div>`). Validating the RENDERED bytes —
+ * not the raw model output — is what makes a pass here equal to a pass in
+ * `mintlify validate` and the deploy.
+ *
+ * On exhaustion it THROWS (never returns a partial), so the caller's write is
+ * unreachable and no invalid page is ever written or cached — the same
+ * fail-loud contract translateContent already enforces for max_tokens
+ * truncation. Transport/auth/max_tokens errors from translateContent propagate
+ * unchanged and consume no attempt: only *validity* failures retry.
+ */
+export async function translateValidated(opts: {
+  source: string;
+  lang: string;
+  langName: string;
+  model?: string;
+  /** Label for the per-attempt warning line, e.g. `agenteye/cli.mdx [de]`. */
+  label: string;
+  /** Turn raw model output into the exact bytes that will be written. */
+  render: (raw: string) => string;
+  /** Validate the rendered bytes; return an error message, or null if valid. */
+  validate: (rendered: string) => Promise<string | null>;
+}): Promise<{
+  rendered: string;
+  inputTokens: number;
+  outputTokens: number;
+  attempts: number;
+}> {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let lastError = "";
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const feedback: RetryFeedback | undefined =
+      attempt > 1
+        ? { attempt, maxAttempts: MAX_ATTEMPTS, error: lastError }
+        : undefined;
+
+    // No try/catch: a transport/auth/max_tokens throw is not a validity
+    // failure — let it propagate so it is never silently retried as one.
+    const result = await translateContent(
+      opts.source,
+      opts.lang,
+      opts.langName,
+      opts.model,
+      feedback,
+    );
+    inputTokens += result.inputTokens;
+    outputTokens += result.outputTokens;
+
+    if (result.translated.trim() === "") {
+      // An empty response is a validity failure, not a usable page — resample
+      // rather than write a blank file.
+      lastError =
+        "The translation was empty. Return the full translated document.";
+      console.warn(
+        `  ${opts.label} -> attempt ${attempt}/${MAX_ATTEMPTS} produced empty output; retrying`,
+      );
+      continue;
+    }
+
+    const rendered = opts.render(result.translated);
+    const error = await opts.validate(rendered);
+    if (error === null) {
+      return { rendered, inputTokens, outputTokens, attempts: attempt };
+    }
+
+    lastError = error;
+    console.warn(
+      `  ${opts.label} -> attempt ${attempt}/${MAX_ATTEMPTS} failed validation: ${error.split("\n")[0]}`,
+    );
+  }
+
+  throw new Error(
+    `translation into ${opts.langName} (${opts.lang}) still fails validation ` +
+      `after ${MAX_ATTEMPTS} attempt(s): ${lastError.split("\n")[0]}`,
+  );
+}

package/scripts/translate-docs/types.ts

@@ -43,4 +43,10 @@ export interface TranslationResult {
   inputTokens: number;
   outputTokens: number;
   cached: boolean;
+  /**
+   * Total translation attempts spent (1 = valid on first try). Optional so the
+   * cached / dry-run result literals need no change; absent means "not
+   * translated this run" (cached) or "1".
+   */
+  attempts?: number;
 }

package/scripts/translate-docs/validate-translation.ts

@@ -0,0 +1,132 @@
+/**
+ * Generation-time validation for a freshly translated page.
+ *
+ * `findTranslationError` runs the exact checks the Mintlify deploy performs —
+ * frontmatter YAML then MDX body — plus one the deploy cannot: frontmatter
+ * KEY-PARITY against the English source. It is called on the exact bytes about
+ * to be written to disk (post-sanitize, post-link-rewrite), so a page that
+ * passes here is a page `mintlify validate` and the deploy accept.
+ *
+ * Why a translation-specific wrapper instead of `findPageError` alone:
+ *  - Frontmatter YAML (class A): the model re-emits an inner `"` unescaped into
+ *    a double-quoted `title:`/`description:` value, breaking the YAML. This is
+ *    the class that failed run 29575781632; `findFrontmatterError` catches it.
+ *  - Key parity (class B): the model drops the frontmatter block entirely, or
+ *    renames a key. A dropped block is still *valid YAML* (mintlify tolerates
+ *    it, deriving the title from the slug), so only comparing against the
+ *    source's keys catches it. This is deliberately stricter than mintlify —
+ *    the keys are prompt-forbidden to change, so it fails ~never but converts
+ *    a silent content regression into a retry.
+ *  - MDX body (classes C+): stray `<slug>`, `{#anchor}`, unmatched fence,
+ *    swallowed `</div>` — `findMdxParseError` catches these.
+ *
+ * The message returned is written for a MODEL to act on: it names the failing
+ * construct and, for a body error, quotes the offending line, so the retry has
+ * a concrete defect to fix rather than a bare line number the RTL/README
+ * wrappers would have offset anyway.
+ */
+import { findFrontmatterError, findMdxParseError } from "../validate-mdx";
+import YAML from "yaml";
+
+// Same matcher as validate-mdx.ts; duplicated locally so this module owns its
+// frontmatter extraction and does not depend on an internal export.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+
+/**
+ * The sorted top-level keys of a page's frontmatter, or `null` when the page
+ * has no frontmatter block or its block is not a key/value mapping (an
+ * unparseable or scalar block). Callers distinguish "no block" from a YAML
+ * error separately via `findFrontmatterError`.
+ */
+function frontmatterKeys(page: string): string[] | null {
+  const match = FRONTMATTER_RE.exec(page);
+  if (!match) return null;
+  try {
+    const doc = YAML.parse(match[1]);
+    if (doc && typeof doc === "object" && !Array.isArray(doc)) {
+      return Object.keys(doc).sort();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A ±2-line window around `line` (1-based), the failing line prefixed `> ` and
+ * its neighbours `  `. Empty string when `line` is undefined.
+ */
+function excerpt(page: string, line?: number): string {
+  if (!line) return "";
+  const lines = page.split("\n");
+  const start = Math.max(1, line - 2);
+  const end = Math.min(lines.length, line + 2);
+  const out: string[] = [];
+  for (let n = start; n <= end; n++) {
+    out.push(`${n === line ? "> " : "  "}${lines[n - 1]}`);
+  }
+  return out.join("\n");
+}
+
+const backticked = (keys: string[]): string =>
+  keys.map((k) => `\`${k}\``).join(", ");
+
+/**
+ * Validate a rendered translation against its English `source`. Returns a
+ * model-actionable error message, or `null` when the page is publishable.
+ */
+export async function findTranslationError(
+  rendered: string,
+  source: string,
+): Promise<string | null> {
+  // Validate the rendered frontmatter block FIRST, for every source shape —
+  // even when the source had none. findMdxParseError (below) blanks a leading
+  // `---` block before compiling, so a malformed block the model *added* to a
+  // frontmatter-less page would otherwise be invisible here yet still break the
+  // Mintlify deploy. Closing exactly that blind spot is this module's job, so
+  // it must hold regardless of whether the source has frontmatter.
+  const fm = findFrontmatterError(rendered);
+  if (fm) {
+    return (
+      "The YAML frontmatter (the `---` block at the top of the file) does " +
+      `not parse:\n\n${fm.message}`
+    );
+  }
+
+  const sourceKeys = frontmatterKeys(source);
+  if (sourceKeys) {
+    // The source has frontmatter, so the translation must carry the same keys.
+    // (Its block, if present, already parsed cleanly above.)
+    const keys = frontmatterKeys(rendered);
+    if (keys === null) {
+      return (
+        "The YAML frontmatter is missing. The English source starts with a " +
+        `\`---\` block containing ${backticked(sourceKeys)}; the translation ` +
+        "must start with the same block — translate the values, keep the keys."
+      );
+    }
+    // Subset check BY DESIGN: a missing or renamed key is a content regression
+    // (the page loses its title/description), so reject it. An *extra* key is
+    // harmless — Mintlify ignores unknown frontmatter keys — so tolerate it
+    // rather than burn a retry (and risk exhausting the whole batch) on a page
+    // that would deploy fine. Reject content loss; allow harmless additions.
+    const missing = sourceKeys.filter((k) => !keys.includes(k));
+    if (missing.length > 0) {
+      return (
+        `The YAML frontmatter keys changed. Expected ${backticked(sourceKeys)} ` +
+        `but got ${backticked(keys)}. Translate the values, never rename or ` +
+        "drop a key."
+      );
+    }
+  }
+
+  const body = await findMdxParseError(rendered);
+  if (body) {
+    const snippet = excerpt(rendered, body.line);
+    return `The MDX body does not parse: ${body.message}${
+      snippet ? `\n\n${snippet}` : ""
+    }`;
+  }
+
+  return null;
+}