Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

tests/test_examples.py

@@ -93,8 +93,25 @@ async def test_desktop(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
         assert "file2.txt" in content.text
 
 
-# TODO(v2): Change back to README.md when v2 is released
-@pytest.mark.parametrize("example", list(find_examples("README.v2.md")), ids=str)
+# TODO(v2): Change back to README.md when v2 is released.
+# `--8<--` include directives lint clean as Python, so pages built from
+# `docs_src/` includes cost nothing here; the real validation of those files is
+# pyright + ruff + tests/docs_src/.
+@pytest.mark.parametrize(
+    "example",
+    list(
+        find_examples(
+            "README.v2.md",
+            "docs/index.md",
+            "docs/installation.md",
+            "docs/tutorial",
+            "docs/run",
+            "docs/client",
+            "docs/advanced",
+        )
+    ),
+    ids=str,
+)
 def test_docs_examples(example: CodeExample, eval_example: EvalExample):
     ruff_ignore: list[str] = ["F841", "I001", "F821"]  # F821: undefined names (snippets lack imports)