failproofai 1.0.1 → 1.0.2-beta.0

package/scripts/build-policy-pack.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+/**
+ * Emit the builtin policies AS a policy pack.
+ *
+ * This is the dress rehearsal for builtins leaving the npm package. It produces
+ * exactly what a third-party publisher would upload to a GitHub release — a
+ * manifest, ONE bundled entry artifact, and a SHA256SUMS — so the same lane that
+ * loads a stranger's pack can be pointed at ours and proved to produce identical
+ * enforcement.
+ *
+ * Nothing on the hook path reads the output. `builtin-pack-conformance.test.ts`
+ * loads it into a scratch registry and compares. That is the point: it turns the
+ * eventual switch-over into a comparison someone already ran, rather than a leap.
+ *
+ * ## Two things it deliberately does
+ *
+ * **One file.** Transitive local imports are rewritten by the loader with no
+ * integrity check of their own — only the ENTRY is content-addressed — so a
+ * multi-file pack could not honestly claim to be digest-pinned. Bundling is what
+ * makes the digest mean what it says.
+ *
+ * ## Runs under bun, not node
+ *
+ * It imports `policy-catalog.ts` directly for the manifest. Node cannot resolve
+ * an extensionless TypeScript specifier at all before 22, and this repo targets
+ * node >= 20.9 — on 22 it "works" while printing a reparse warning, which is the
+ * worst of both: green here, broken on a supported version. bun reads TS
+ * natively, and every other build step in this repo is already bun.
+ *
+ * **It omits the `alwaysOn` policy.** `block-failproofai-commands` is the guard
+ * that stops an agent disabling failproofai, it ships compiled in, and
+ * `pack-manifest.ts` REFUSES any pack that declares `alwaysOn`. A pack containing
+ * it would be rejected by our own loader — correctly.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// `--out <dir>` lets the conformance test generate into a temp directory rather
+// than depending on a build step having run first — the unit suite and the build
+// are separate CI jobs, so a test that assumed `policy-pack/` existed would be
+// green locally and skipped-or-broken in CI.
+const outArg = process.argv.indexOf("--out");
+const OUT_DIR = outArg !== -1 && process.argv[outArg + 1]
+  ? resolve(process.argv[outArg + 1])
+  : join(ROOT, "policy-pack");
+// Not `failproofai/builtins`. These stop being builtins the moment they ship as
+// a pack, and an id is the most durable place a retired word can hide — it ends
+// up in every machine's installed.json and in the listing every user reads.
+const PACK_ID = "failproofai/core";
+const ENTRY_ASSET = "failproofai-pack.mjs";
+const MANIFEST_ASSET = "failproofai-pack.json";
+const CHECKSUMS_ASSET = "SHA256SUMS";
+
+const version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+
+// A generated entry that registers every non-alwaysOn builtin through the public
+// policy API — the same API a third-party pack uses. `failproofai` stays external
+// so the loader's shim resolves it, exactly as it does for any other pack.
+const entrySource = `
+import { customPolicies } from "failproofai";
+import { BUILTIN_POLICIES } from ${JSON.stringify(join(ROOT, "src/hooks/builtin-policies.ts"))};
+
+for (const policy of BUILTIN_POLICIES) {
+  if (policy.alwaysOn) continue;
+  customPolicies.add({
+    name: policy.name,
+    description: policy.description,
+    match: policy.match,
+    fn: policy.fn,
+  });
+}
+`;
+
+rmSync(OUT_DIR, { recursive: true, force: true });
+mkdirSync(OUT_DIR, { recursive: true });
+
+const tempEntry = join(OUT_DIR, ".entry.generated.ts");
+writeFileSync(tempEntry, entrySource, "utf8");
+try {
+  execFileSync(
+    "bun",
+    ["build", "--target=node", "--format=esm", "--external", "failproofai",
+     "--outfile", join(OUT_DIR, ENTRY_ASSET), tempEntry],
+    { cwd: ROOT, stdio: ["pipe", "pipe", "inherit"] },
+  );
+} finally {
+  rmSync(tempEntry, { force: true });
+}
+
+// The manifest's policy list comes from the CATALOG, never from the bundle —
+// which is the whole reason the catalog is pure literal data. `pack add`
+// validates these with the loader's own rules, so a shape the loader would
+// refuse fails this build rather than shipping.
+const { POLICY_CATALOG } = await import(join(ROOT, "src/hooks/policy-catalog.ts"));
+const policies = POLICY_CATALOG.filter((p) => !p.alwaysOn).map((p) => ({ ...p }));
+
+const manifest = JSON.stringify(
+  { id: PACK_ID, version, effect: "enforce", policies },
+  null,
+  2,
+) + "\n";
+writeFileSync(join(OUT_DIR, MANIFEST_ASSET), manifest, "utf8");
+
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const entryBytes = readFileSync(join(OUT_DIR, ENTRY_ASSET));
+writeFileSync(
+  join(OUT_DIR, CHECKSUMS_ASSET),
+  `${sha(Buffer.from(manifest))}  ${MANIFEST_ASSET}\n${sha(entryBytes)}  ${ENTRY_ASSET}\n`,
+  "utf8",
+);
+
+const omitted = POLICY_CATALOG.filter((p) => p.alwaysOn).map((p) => p.name);
+console.log(
+  `[policy-pack] ${PACK_ID}@${version} — ${policies.length} policies, ` +
+  `${(entryBytes.length / 1024).toFixed(1)} KB entry` +
+  (omitted.length ? `; omitted alwaysOn: ${omitted.join(", ")}` : ""),
+);

package/scripts/changelog-section.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Print one version's section out of a CHANGELOG, for a GitHub Release body.
+
+    changelog-section.py <changelog> <version>
+
+Both PyPI publish workflows call this from `preflight` — BEFORE anything is built
+and long before anything is uploaded — so a release with no notes fails at the one
+point in the pipeline where failing is free. It cannot be fixed afterwards: PyPI
+never releases a version for reuse, so "publish it again, with notes this time" is
+not an available remedy, and the GitHub Release would stand empty against a
+version that is permanently on the index.
+
+The heading grammar is the one CLAUDE.md fixes for the root changelog and which
+the per-package files follow:
+
+    ## 0.0.1b1 — 2026-08-24
+
+The date is not parsed; only the version is matched, and it is matched with a
+trailing word boundary so a request for `0.0.1b1` cannot be answered by
+`0.0.1b10`'s section — which is a real hazard once a beta counter passes nine,
+and one that would put the WRONG release's notes on a tag with no error anywhere.
+
+Stdlib only, same reason as `python-version.py`: it runs in the job that holds no
+publishing identity precisely because it installs nothing.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+
+class SectionError(Exception):
+    """A message a maintainer can act on, printed without a traceback."""
+
+
+def extract(text: str, version: str) -> str:
+    """The body under `## <version>`, up to the next `## ` heading."""
+    heading = re.compile(rf"^##[ \t]+{re.escape(version)}\b.*$", re.MULTILINE)
+    match = heading.search(text)
+    if not match:
+        raise SectionError(
+            f"no '## {version}' section — add one before releasing, or the tag "
+            f"gets a release with nothing in it"
+        )
+
+    rest = text[match.end():]
+    nxt = re.search(r"^##[ \t]", rest, re.MULTILINE)
+    body = (rest[: nxt.start()] if nxt else rest).strip()
+
+    if not body:
+        # A heading with nothing under it is the same failure as no heading at
+        # all, and is what you get from stamping a version onto an empty section.
+        raise SectionError(f"the '## {version}' section is empty")
+    return body
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        print(__doc__ or "", file=sys.stderr)
+        return 2
+    path, version = argv[1], argv[2]
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise SectionError(f"cannot read {path}: {exc}") from exc
+    print(extract(text, version))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main(sys.argv))
+    except SectionError as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(1) from None

package/scripts/prune-standalone.mjs

@@ -119,6 +119,9 @@ const STANDALONE_ROOT_PRUNE = [
   // plugin/extension dirs are shipped from the package root by `files`, not
   // from inside the standalone bundle.
   "integration-suite", "pi-extension", "openclaw-plugin", "docker-hook-sync",
+  // Generated by build:pack and shipped from the root by `files`, same as the
+  // two above — without this it lands in the tarball twice.
+  "policy-pack",
 ];
 const STANDALONE_ROOT_PRUNE_FILES = [
   // Top-level markdown / licenses / docs

package/scripts/python-version.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Version arithmetic for the two Python packages, `fp-cloud-cli` and `failproofai-sdk`.
+
+Both publish workflows call this; it is the ONE place the release scheme is written
+down, so the two pipelines cannot drift into disagreeing about what comes next.
+
+    resolve <version-file> [<dist>]     -> key=value lines for $GITHUB_OUTPUT
+    write   <version-file> <version>    -> rewrite __version__ in place
+
+Given a dist name, `resolve` also emits the release tag: `<dist>-v<version>`, e.g.
+`fp-cloud-cli-v0.0.1b1`. Namespaced rather than the bare `vX.Y.Z` the npm package uses,
+because three release lines share one repository and one tag namespace — a bare
+`v0.0.1b1` would read as a release of `failproofai` itself, and `gh release list`
+would interleave all three with no way to tell them apart.
+
+THE SCHEME. It mirrors `publish.yml`'s npm rule, spelled in PEP 440 rather than
+semver, because PyPI has no dist-tags: there is no movable `beta` pointer to
+publish behind, so the pre-release marker in the version string is the entire
+channel mechanism.
+
+    beta    X.Y.ZbN  ->  X.Y.Zb(N+1)      another beta off the same base
+    stable  X.Y.Z    ->  X.Y.(Z+1)b0      open the next patch's beta line
+
+`b` and not `-beta.`: `0.1.0-beta.1` is not a PEP 440 version at all, and pip
+would reject the sdist name. `b0` and not `b1` after a stable, because that is
+what npm's rule does (`X.Y.(Z+1)-beta.0`) and a release scheme that differs
+between two of this repo's registries for no reason is a scheme nobody can
+recite from memory.
+
+WHY NON-CANONICAL SPELLINGS ARE REJECTED RATHER THAN ACCEPTED. `0.0.01b1`,
+`0.0.1b01`, `1.2.3-beta.1` and `v1.2.3` are all legal PEP 440 and all normalise to
+something else on the way to PyPI — so the file would say one thing, the wheel
+another, and preflight's "is this already published" check would ask PyPI about a
+third. Every consumer here compares version STRINGS, so this module normalises and
+refuses anything that is not already in its final form, naming what PyPI would have
+turned it into.
+
+Stdlib only, and deliberately: this runs in the preflight job, which is the one
+job in those workflows that has no publishing identity precisely BECAUSE it runs
+before anything is installed. A dependency here would put third-party code back
+into it.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+# `__version__ = "..."` — matched, never exec'd. Importing the module would run
+# whatever else the file grew, in a job that is about to be handed a token.
+_ASSIGNMENT = re.compile(r"""(__version__\s*=\s*)(["'])([^"']+)(\2)""")
+
+# The two shapes the scheme knows how to advance.
+_STABLE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+_BETA = re.compile(r"^(\d+)\.(\d+)\.(\d+)b(\d+)$")
+
+# PEP 440's own pre-release spellings, and the canonical form each collapses to.
+_PRE_LABELS = {
+    "alpha": "a",
+    "a": "a",
+    "beta": "b",
+    "b": "b",
+    "c": "rc",
+    "pre": "rc",
+    "preview": "rc",
+    "rc": "rc",
+}
+
+# PEP 440, verbatim from the spec's appendix. Used to normalise, and to tell "a
+# version this scheme will not advance" (an rc, a .post, a .dev — publishable, no
+# auto-bump) apart from "not a version at all" (a typo — refuse before a build).
+_PEP440 = re.compile(
+    r"""^\s*v?
+    (?:(?P<epoch>[0-9]+)!)?
+    (?P<release>[0-9]+(?:\.[0-9]+)*)
+    (?P<pre>[-_.]?(?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)[-_.]?(?P<pre_n>[0-9]+)?)?
+    (?P<post>(?:-(?P<post_n1>[0-9]+))|(?:[-_.]?(?P<post_l>post|rev|r)[-_.]?(?P<post_n2>[0-9]+)?))?
+    (?P<dev>[-_.]?dev[-_.]?(?P<dev_n>[0-9]+)?)?
+    (?:\+(?P<local>[a-z0-9]+(?:[-_.][a-z0-9]+)*))?
+    \s*$""",
+    re.VERBOSE | re.IGNORECASE,
+)
+
+
+class VersionError(Exception):
+    """A message a maintainer can act on, printed without a traceback."""
+
+
+def read_version(path: str) -> str:
+    """The `__version__` literal in a `_version.py`, exactly as written."""
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise VersionError(f"cannot read {path}: {exc}") from exc
+
+    found = _ASSIGNMENT.findall(text)
+    if not found:
+        raise VersionError(f"no __version__ assignment in {path}")
+    if len(found) > 1:
+        # Two assignments means the last one wins at import time and the first
+        # one is what a careless regex edit would rewrite. Refuse rather than
+        # guess which is live.
+        raise VersionError(f"{len(found)} __version__ assignments in {path}; expected exactly 1")
+    return found[0][2]
+
+
+def normalize(version: str) -> str:
+    """The form PyPI will store, per PEP 440's normalisation rules."""
+    match = _PEP440.match(version)
+    if not match:
+        raise VersionError(f"'{version}' is not a valid PEP 440 version")
+
+    out = ""
+    epoch = match.group("epoch")
+    if epoch and int(epoch):
+        out += f"{int(epoch)}!"
+    out += ".".join(str(int(part)) for part in match.group("release").split("."))
+    if match.group("pre"):
+        out += _PRE_LABELS[match.group("pre_l").lower()] + str(int(match.group("pre_n") or 0))
+    if match.group("post"):
+        out += f".post{int(match.group('post_n1') or match.group('post_n2') or 0)}"
+    if match.group("dev"):
+        out += f".dev{int(match.group('dev_n') or 0)}"
+    local = match.group("local")
+    if local:
+        out += "+" + local.lower().replace("_", ".").replace("-", ".")
+    return out
+
+
+def classify(version: str) -> tuple[str, str]:
+    """`(scheme, next_version)`. `next_version` is empty when the scheme cannot advance."""
+    canonical = normalize(version)
+    if canonical != version:
+        # Checked before the scheme, not inside it, so it also catches the shapes
+        # the scheme does not advance — `1.2.3-beta.1` publishes as `1.2.3b1`, and
+        # a preflight that asked PyPI about the former learned nothing about the
+        # version actually going up.
+        raise VersionError(
+            f"'{version}' is not canonical — PyPI would normalise it to '{canonical}', "
+            "so the file, the wheel and the published version would disagree"
+        )
+
+    match = _BETA.match(version)
+    if match:
+        major, minor, patch, beta = (int(g) for g in match.groups())
+        return "beta", f"{major}.{minor}.{patch}b{beta + 1}"
+
+    match = _STABLE.match(version)
+    if match:
+        major, minor, patch = (int(g) for g in match.groups())
+        return "stable", f"{major}.{minor}.{patch + 1}b0"
+
+    # Canonical, valid, and not one of the two shapes: an rc, a .post, a .dev, an
+    # epoch. PyPI takes it, so publishing is not blocked — but nothing here knows
+    # what should follow it, and inventing a successor is how a release line
+    # silently forks. The workflow warns and leaves main's version for a human.
+    return "other", ""
+
+
+def is_prerelease(version: str) -> bool:
+    match = _PEP440.match(version)
+    if not match:
+        raise VersionError(f"'{version}' is not a valid PEP 440 version")
+    return bool(match.group("pre") or match.group("dev"))
+
+
+#: Tag prefixes this repository already uses, and must not be confused with. The
+#: npm package tags bare `vX.Y.Z`; a Python release tag must never be mistakable
+#: for one, in `gh release list`, in the repo's release feed, or by the CLI, which
+#: builds its daemon download URLs out of `v<version>` tags.
+_RESERVED_TAG_PREFIX = "v"
+
+
+def release_tag(dist: str, version: str) -> str:
+    tag = f"{dist}-v{version}"
+    if not dist or dist.startswith(_RESERVED_TAG_PREFIX) and dist[1:2].isdigit():
+        raise VersionError(f"dist name '{dist}' would produce a tag mistakable for an npm release tag")
+    return tag
+
+
+def resolve(path: str, dist: str | None = None) -> str:
+    version = read_version(path)
+    scheme, following = classify(version)
+    lines = [
+        f"version={version}",
+        f"scheme={scheme}",
+        f"is_prerelease={'true' if is_prerelease(version) else 'false'}",
+        f"next_version={following}",
+    ]
+    if dist:
+        lines.append(f"tag={release_tag(dist, version)}")
+    return "\n".join(lines)
+
+
+def write(path: str, version: str) -> str:
+    """Rewrite the literal in place, leaving every other byte of the file alone."""
+    scheme, _ = classify(version)  # refuses a typo before it reaches a commit
+    if scheme == "other":
+        # `write` is only ever called with a version this module computed, so
+        # reaching here means someone wired it to an arbitrary string.
+        raise VersionError(f"'{version}' is outside the release scheme; set it by hand")
+
+    with open(path, encoding="utf-8") as handle:
+        text = handle.read()
+    replaced, count = _ASSIGNMENT.subn(
+        lambda m: f"{m.group(1)}{m.group(2)}{version}{m.group(4)}", text
+    )
+    if count != 1:
+        raise VersionError(f"expected exactly 1 __version__ assignment in {path}, found {count}")
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(replaced)
+    return version
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) >= 3 and argv[1] == "resolve":
+        print(resolve(argv[2], argv[3] if len(argv) >= 4 else None))
+        return 0
+    if len(argv) >= 4 and argv[1] == "write":
+        print(write(argv[2], argv[3]))
+        return 0
+    print(__doc__ or "", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main(sys.argv))
+    except VersionError as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(1) from None

package/scripts/translate-docs/cli.ts

@@ -39,6 +39,11 @@ const { values: args } = parseArgs({
     validate: { type: "boolean", default: false },
     prune: { type: "boolean", default: false },
     "no-prune": { type: "boolean", default: false },
+    // Publish what succeeded instead of discarding it. One page failing used to
+    // exit 1, which made the box job die before its push — on 2026-08-18 that
+    // threw away 782 good translations (2.7M tokens) because ONE page overran
+    // the output limit. Opt-in, so CI and hand runs keep failing loudly.
+    "allow-partial": { type: "boolean", default: false },
     model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -56,6 +61,8 @@ Options:
       --readme-only        Only translate the README
       --docs-only          Only translate Mintlify docs
       --dry-run            Show what would be translated without calling the API
+      --allow-partial      Exit 0 when SOME pages translated, listing the failures
+                           (default: any failure exits 1 and publishes nothing)
   -f, --force              Ignore cache, re-translate everything
       --update-nav         Regenerate docs.json navigation after translation
       --validate           Check all nav references resolve to files
@@ -441,6 +448,20 @@ async function main() {
   }
 
   if (errors.length > 0) {
+    // Printed either way — a partial run must never read as a clean one.
+    console.log(`\nFAILED PAGES (${errors.length}):`);
+    for (const e of errors) {
+      console.log(`  ${e.source} [${e.lang}]: ${e.error}`);
+    }
+    if (args["allow-partial"] && translated.length > 0) {
+      // A stable marker the box job greps for, so the failure reaches Slack and
+      // the PR body instead of being buried in a 700-line log.
+      console.log(
+        `\nPARTIAL RUN — ${translated.length} page(s) translated, ${errors.length} failed. ` +
+          `Publishing what succeeded.`,
+      );
+      return;
+    }
     process.exit(1);
   }
 }

package/scripts/translate-docs/mintlify-nav.ts

@@ -1,19 +1,29 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getLanguageByCode, NAV_TRANSLATIONS } from "./config";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DOCS_JSON_PATH = join(__dirname, "..", "..", "docs", "docs.json");
+const DOCS_DIR = join(__dirname, "..", "..", "docs");
+const DOCS_JSON_PATH = join(DOCS_DIR, "docs.json");
 
 interface NavGroup {
   group: string;
-  pages: string[];
+  // OPTIONAL, and both of these are why: a Mintlify group may carry `pages`, or
+  // nested `groups`, or neither — the docs rebuild introduced a group whose
+  // content is an `openapi` spec and has no pages at all. `pages` entries are
+  // likewise strings OR nested groups. Typing these as required is what let
+  // `group.pages.map` crash the nightly run.
+  pages?: (string | NavGroup)[];
+  groups?: NavGroup[];
+  // Everything else (expanded, icon, openapi, …) rides along untouched.
+  [key: string]: unknown;
 }
 
 interface NavTab {
   tab: string;
   groups: NavGroup[];
+  [key: string]: unknown;
 }
 
 interface LanguageNav {
@@ -76,9 +86,33 @@ export function getNavigationPageReferences(
  * Build a navigation entry for a specific language by transforming the
  * English navigation structure.
  */
+/**
+ * Does the localized file for a nav entry exist on disk?
+ *
+ * Defaults to "yes" so the pure transform stays testable with fixtures, and the
+ * REAL check is injected by updateDocsJson / localizeProductsNavigation, which
+ * are the two paths that write docs.json.
+ */
+export type PageExists = (relativePath: string) => boolean;
+
+const fileOnDisk: PageExists = (rel) => existsSync(join(DOCS_DIR, rel));
+
+/**
+ * Keep a group only if it still carries something to render. Dropping every
+ * missing page can empty a group, and an empty group is its own validation
+ * error — but a group whose content is an `openapi` spec has no pages by
+ * design and must survive.
+ */
+function hasContent(group: NavGroup): boolean {
+  if (Array.isArray(group.pages) && group.pages.length > 0) return true;
+  if (Array.isArray(group.groups) && group.groups.length > 0) return true;
+  return !Array.isArray(group.pages) && !Array.isArray(group.groups);
+}
+
 export function buildLanguageNav(
   englishTabs: NavTab[],
   lang: string,
+  exists: PageExists = () => true,
 ): LanguageNav {
   const t = NAV_TRANSLATIONS[lang];
   if (!t) throw new Error(`No nav translations for language: ${lang}`);
@@ -97,13 +131,47 @@ export function buildLanguageNav(
     Examples: t.examples,
   };
 
-  const tabs: NavTab[] = englishTabs.map((tab) => ({
-    tab: tabNameMap[tab.tab] || tab.tab,
-    groups: tab.groups.map((group) => ({
-      group: groupNameMap[group.group] || group.group,
-      pages: group.pages.map((page) => `${lang}/${page}`),
-    })),
-  }));
+  // Rebuilt by SPREADING the English group, not by picking two fields off it.
+  // The old form silently dropped every other key — `expanded`, `icon`,
+  // `openapi` — so a localized nav quietly lost them, and it crashed outright
+  // on the first group that had no `pages` at all.
+  const localizeGroup = (group: NavGroup): NavGroup => {
+    const out: NavGroup = { ...group, group: groupNameMap[group.group] || group.group };
+    if (Array.isArray(group.pages)) {
+      // A page entry is a path to prefix, or a nested group to recurse into.
+      //
+      // A path is DROPPED when its localized file is not on disk. The English
+      // tree is the source of the nav, so without this every English page gets
+      // an entry in all fourteen languages whether or not it was translated —
+      // and `mintlify validate` rejects the run. That took down a nightly job
+      // that had already translated 784 pages: one page failed, the nav still
+      // referenced it in that language, and every successful page was discarded
+      // with it. Omitting the entry is the honest state: the page does not
+      // exist in that language yet.
+      out.pages = group.pages
+        .map((page) =>
+          typeof page === "string" ? `${lang}/${page}` : localizeGroup(page),
+        )
+        .filter((page) =>
+          typeof page === "string" ? exists(`${page}.mdx`) : hasContent(page),
+        );
+    }
+    if (Array.isArray(group.groups)) {
+      out.groups = group.groups.map(localizeGroup).filter(hasContent);
+    }
+    // No pages and no groups (an `openapi` group): carried through as-is. The
+    // spec is not translated, and dropping the group would remove the API
+    // reference from every non-English nav.
+    return out;
+  };
+
+  const tabs: NavTab[] = englishTabs
+    .map((tab) => ({
+      ...tab,
+      tab: tabNameMap[tab.tab] || tab.tab,
+      groups: (tab.groups ?? []).map(localizeGroup).filter(hasContent),
+    }))
+    .filter((tab) => tab.groups.length > 0);
 
   return {
     language: getLanguageByCode(lang)?.mintlifyCode ?? lang,
@@ -125,10 +193,11 @@ export function readDocsConfig(): Record<string, unknown> {
 export function generateLanguagesArray(
   englishTabs: NavTab[],
   langCodes: string[],
+  exists: PageExists = () => true,
 ): LanguageNav[] {
   // English first (default)
   const english: LanguageNav = { language: "en", tabs: englishTabs };
-  const others = langCodes.map((code) => buildLanguageNav(englishTabs, code));
+  const others = langCodes.map((code) => buildLanguageNav(englishTabs, code, exists));
   return [english, ...others];
 }
 
@@ -136,6 +205,9 @@ export function generateLanguagesArray(
 export function localizeProductsNavigation(
   products: unknown[],
   langCodes: string[],
+  // Defaults to the real disk check, like updateDocsJson — injectable so the
+  // pure transform can be exercised against fixtures that are not on disk.
+  exists: PageExists = fileOnDisk,
 ): Record<string, unknown>[] {
   return products.map((value) => {
     const product = value as Record<string, unknown>;
@@ -149,7 +221,7 @@ export function localizeProductsNavigation(
     const { tabs: _tabs, ...rest } = product;
     return {
       ...rest,
-      languages: generateLanguagesArray(englishTabs, langCodes),
+      languages: generateLanguagesArray(englishTabs, langCodes, exists),
     };
   });
 }
@@ -177,7 +249,7 @@ export function updateDocsJson(langCodes: string[]): void {
   }
 
   const newNav: Record<string, unknown> = {
-    languages: generateLanguagesArray(englishTabs, langCodes),
+    languages: generateLanguagesArray(englishTabs, langCodes, fileOnDisk),
   };
   if (nav.global) {
     newNav.global = nav.global;