@@ -30,5 +30,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      # Stdlib only — these tests stub out gh and never call the network.
+      # pyyaml only: the tests stub out gh, never call the network, and the
+      # Anthropic SDK is imported lazily so it isn't needed here.
+      - run: pip install pyyaml
       - run: python -m unittest discover -s pipeline -p "test_*.py" -v
@@ -177,6 +177,12 @@ def page_frontmatter(page_path):
     return None, None  # page listed in nav but file missing
 
 
+def has_child_pages(all_pages, page_path):
+    """Whether other nav entries sit under this one, making it a hub page."""
+    prefix = page_path + "/"
+    return any(p.startswith(prefix) for p in all_pages)
+
+
 def slug(page_path):
     return page_path.rsplit("/", 1)[-1].lower()
 
@@ -331,14 +337,17 @@ def detect_gaps(docs_json, endpoints, families, section=None, force=False):
 
     # --- Doc-quality checks on non-reference pages ------------------------ #
     if not section:
-        for p in all_doc_pages(docs_json, apiref_tab):
+        doc_pages = all_doc_pages(docs_json, apiref_tab)
+        for p in doc_pages:
             fm, content = page_frontmatter(p)
             if fm is None:
                 continue
             if not fm.get("description"):
                 gaps.append(gap("missing_description", "low", None, path=page_file(p) or p,
                                 desc=f"{p} has no frontmatter description"))
-            if len(strip_frontmatter(content).split()) < 100:
+            # A page with children is a hub: it's short because the content sits
+            # on the child pages. Padding it out is the wrong fix, so don't ask.
+            if len(strip_frontmatter(content).split()) < 100 and not has_child_pages(doc_pages, p):
                 gaps.append(gap("thin_page", "medium", None, path=page_file(p) or p,
                                 desc=f"{p} has under 100 words"))
 
 
@@ -67,6 +67,21 @@ def load_file(path):
         return ""
 
 
+def load_existing_page(gap):
+    """Content of the page a gap edits. Raises rather than returning nothing.
+
+    An empty read would turn "expand this page" into "write one from scratch"
+    and silently discard the real content.
+    """
+    page_path = REPO_ROOT / gap.get("path", "")
+    if not page_path.is_file():
+        raise FileNotFoundError(f"no file at '{gap.get('path', '')}' for {gap['type']} gap")
+    content = load_file(page_path)
+    if not content.strip():
+        raise ValueError(f"{gap['path']} is empty, refusing to rewrite it from nothing")
+    return content
+
+
 def load_openapi_for_tags(tags):
     """Extract the portion of the OpenAPI spec whose endpoints carry any of `tags`."""
     with open(OPENAPI_PATH) as f:
@@ -215,7 +230,7 @@ def build_generation_prompt(gap, family_name, openapi_context, existing_docs_con
 
     elif gap_type == "thin_page":
         page_path = gap.get("path", "")
-        page_content = load_file(REPO_ROOT / page_path)
+        page_content = load_existing_page(gap)
         return f"""Expand this thin page. It currently has only {gap.get('word_count', 0)} words.
 
 Current content of {page_path}:
@@ -232,7 +247,7 @@ def build_generation_prompt(gap, family_name, openapi_context, existing_docs_con
 
     elif gap_type == "missing_code_examples":
         page_path = gap.get("path", "")
-        page_content = load_file(REPO_ROOT / page_path)
+        page_content = load_existing_page(gap)
         return f"""Add code examples to this page. It's a guide but has no runnable code.
 
 Current content of {page_path}:
@@ -249,7 +264,7 @@ def build_generation_prompt(gap, family_name, openapi_context, existing_docs_con
 
     elif gap_type == "missing_description":
         page_path = gap.get("path", "")
-        page_content = load_file(REPO_ROOT / page_path)[:500]
+        page_content = load_existing_page(gap)[:500]
         return f"""Generate a frontmatter description for this page.
 
 Current content of {page_path} (first 500 chars):
 
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Tests for the thin-page hub exemption and for reading the page a gap edits.
+
+    python pipeline/test_hub_and_reads.py
+
+Runs against a temp docs tree, so no repo file is read and none is written.
+"""
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import detect_gaps  # noqa: E402
+import generate  # noqa: E402
+
+
+class TempDocsTree(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+        self._saved = (detect_gaps.REPO_ROOT, generate.REPO_ROOT)
+        detect_gaps.REPO_ROOT = self.root
+        generate.REPO_ROOT = self.root
+        self.addCleanup(self._restore)
+
+    def _restore(self):
+        detect_gaps.REPO_ROOT, generate.REPO_ROOT = self._saved
+        self._tmp.cleanup()
+
+    def write(self, rel, text="---\ntitle: T\n---\n\nSome body copy.\n"):
+        path = self.root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+
+
+class HasChildPagesTest(unittest.TestCase):
+    def test_a_page_with_children_is_a_hub(self):
+        pages = ["docs/notices", "docs/notices/july-2024"]
+        self.assertTrue(detect_gaps.has_child_pages(pages, "docs/notices"))
+
+    def test_a_leaf_is_not(self):
+        self.assertFalse(detect_gaps.has_child_pages(["docs/a", "docs/b"], "docs/a"))
+
+    def test_a_name_prefix_is_not_a_child(self):
+        """'docs/x-ray' must not count as a child of 'docs/x'."""
+        self.assertFalse(detect_gaps.has_child_pages(["docs/x", "docs/x-ray"], "docs/x"))
+
+
+class ThinPageDetectionTest(TempDocsTree):
+    def test_hub_is_not_flagged_but_a_real_thin_page_is(self):
+        short = "---\ntitle: T\ndescription: d\n---\n\nToo short.\n"
+        for page in ("docs/hub", "docs/hub/child", "docs/lonely"):
+            self.write(f"{page}.mdx", short)
+        docs_json = {"navigation": {"tabs": [
+            {"tab": "Home", "pages": ["docs/hub", "docs/hub/child", "docs/lonely"]},
+        ]}}
+
+        thin = [g["description"] for g in detect_gaps.detect_gaps(docs_json, [], {})
+                if g["type"] == "thin_page"]
+        self.assertEqual(sorted(thin), [
+            "docs/hub/child has under 100 words",  # a child can still be thin
+            "docs/lonely has under 100 words",
+        ])
+
+
+class LoadExistingPageTest(TempDocsTree):
+    def test_reads_the_page(self):
+        self.write("docs/a.mdx", "---\ntitle: T\n---\n\nReal content.\n")
+        page = generate.load_existing_page({"type": "thin_page", "path": "docs/a.mdx"})
+        self.assertIn("Real content.", page)
+
+    def test_a_missing_file_raises_instead_of_returning_nothing(self):
+        """An empty read used to become "write this page from scratch"."""
+        with self.assertRaises(FileNotFoundError):
+            generate.load_existing_page({"type": "thin_page", "path": "docs/ghost.mdx"})
+
+    def test_a_directory_raises_file_not_found_not_is_a_directory(self):
+        self.write("docs/a/child.mdx")
+        with self.assertRaises(FileNotFoundError):
+            generate.load_existing_page({"type": "thin_page", "path": "docs/a"})
+
+    def test_an_empty_page_raises(self):
+        self.write("docs/blank.mdx", "   \n")
+        with self.assertRaises(ValueError):
+            generate.load_existing_page({"type": "thin_page", "path": "docs/blank.mdx"})
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)