docs: fail the docs build when the nav references a missing page

Zensical ships a nav entry for a nonexistent page as a broken link with no
diagnostic, even under --strict; MkDocs strict aborted the build. Validate
the materialised nav in build_config.py so the guarantee survives the
migration, and reject an empty generated API nav while at it.

Author: maxisbey

scripts/docs/build_config.py

@@ -23,17 +23,40 @@
 ROOT = Path(__file__).parent.parent.parent
 
 
+def _missing_nav_pages(nav: list, docs_dir: Path) -> list[str]:
+    """Collect nav page references that don't exist under the docs dir.
+
+    Zensical (0.0.48) ships a nav entry for a nonexistent page as a broken
+    link without any diagnostic, even under --strict — MkDocs aborted the
+    build. Validating here keeps that guarantee: the concrete config never
+    leaves this script referencing a page that isn't there.
+    """
+    missing: list[str] = []
+    for entry in nav:
+        value = next(iter(entry.values())) if isinstance(entry, dict) else entry
+        if isinstance(value, list):
+            missing.extend(_missing_nav_pages(value, docs_dir))
+        elif not (docs_dir / value).is_file():
+            missing.append(value)
+    return missing
+
+
 def build_config(output: Path, site_dir: str | None = None) -> None:
     config = yaml.safe_load((ROOT / "mkdocs.yml").read_text(encoding="utf-8"))
 
     api_nav = gen_ref_pages.generate()
+    if not api_nav:
+        raise SystemExit("build_config: gen_ref_pages produced no API pages — did the src/ layout move?")
     for entry in config["nav"]:
         if isinstance(entry, dict) and "API Reference" in entry:
             entry["API Reference"] = api_nav
             break
     else:
         raise SystemExit("build_config: no 'API Reference' entry found in mkdocs.yml nav")
 
+    if missing := _missing_nav_pages(config["nav"], ROOT / "docs"):
+        raise SystemExit(f"build_config: nav references pages that don't exist under docs/: {missing}")
+
     if site_dir is not None:
         config["site_dir"] = site_dir