Add a docs README and link checker

Add tools/check_docs.py to require READMEs only in tracked docs directories,
validate local links and verify every tracked image is linked. Gitignored
generated files such as realism runs are exempt. Document the command and add
unit tests. Python 97/97.

tools/test_check_docs.py

@@ -0,0 +1,52 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import check_docs
+
+
+class CheckDocsTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+
+    def tearDown(self):
+        self.temp.cleanup()
+
+    def _file(self, rel, text=""):
+        path = self.root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        return path
+
+    def test_accepts_tracked_directory_with_links_and_images(self):
+        self._file("docs/README.md", "[x](guide.md)")
+        self._file("docs/guide.md", "guide")
+        self._file("docs/images/preview.png", "png")
+        self._file("docs/images/README.md", "![preview](preview.png)")
+        tracked = [Path("docs/README.md"), Path("docs/guide.md"),
+                   Path("docs/images/preview.png"), Path("docs/images/README.md")]
+        self.assertEqual(check_docs.check_docs(self.root, tracked), [])
+
+    def test_requires_readme_only_in_tracked_dirs(self):
+        self._file("docs/README.md")
+        self._file("docs/ignored/file.txt")
+        tracked = [Path("docs/README.md"), Path("docs/ignored/file.txt")]
+        errors = check_docs.check_docs(self.root, tracked)
+        self.assertTrue(any("docs/ignored" in e for e in errors))
+        # A directory with no tracked files is not required to have a README.
+        self._file("docs/generated/file.txt")
+        tracked = [Path("docs/README.md")]
+        self.assertEqual(check_docs.check_docs(self.root, tracked), [])
+
+    def test_reports_broken_link_and_unlinked_image(self):
+        self._file("docs/README.md", "[broken](missing.md)")
+        self._file("docs/image.png", "png")
+        tracked = [Path("docs/README.md"), Path("docs/image.png")]
+        errors = check_docs.check_docs(self.root, tracked)
+        self.assertTrue(any("broken link" in e for e in errors))
+        self.assertTrue(any("image not linked" in e for e in errors))
+
+
+if __name__ == "__main__":
+    unittest.main()