From 2c51ca919b75791afe4f5331ba7a2b194b51a96d Mon Sep 17 00:00:00 2001
From: Alek <alek@reflex.dev>
Date: Thu, 23 Jul 2026 16:01:37 -0700
Subject: [PATCH 1/2] Decouple CI tests from README

---
 Makefile                             |   2 +-
 scripts/check_claim_guardrails.py    |   1 -
 scripts/check_python_floor.py        |   5 +-
 scripts/verify_local.py              |   4 +-
 spec/process/contributing.md         |  12 +--
 spec/process/production-readiness.md |  17 ++-
 tests/test_docs_examples.py          | 155 ++-------------------------
 tests/test_python_floor.py           |   6 +-
 tests/test_verify_local.py           |  50 ++++-----
 tests/test_verify_sdist.py           |   2 +-
 10 files changed, 46 insertions(+), 208 deletions(-)

diff --git a/Makefile b/Makefile
index ab63b30d..53167a6f 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ help:
 		'  make check-browser    run browser smokes (set CHROMIUM=/path/to/chrome)' \
 		'  make check-conformance run accessibility + Chromium/Firefox/WebKit conformance' \
 		'  make check-docs       run docs examples and public claim guardrails' \
-		'  make check-examples   run README/API examples and Reflex asset registry checks' \
+		'  make check-examples   run canonical API examples and Reflex asset registry checks' \
 		'  make check-security   run standalone HTML safety and client text-sink checks' \
 		'  make check-errors     run public error, LOD, and mutation-safety tests' \
 		'  make check-api        run lazy public API and type-surface checks' \
diff --git a/scripts/check_claim_guardrails.py b/scripts/check_claim_guardrails.py
index cb5f1a07..4f51afc3 100644
--- a/scripts/check_claim_guardrails.py
+++ b/scripts/check_claim_guardrails.py
@@ -18,7 +18,6 @@
 ROOT = Path(__file__).resolve().parents[1]
 DEFAULT_DOCS = (
     "pyproject.toml",
-    "README.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "spec/api/api-examples.md",
diff --git a/scripts/check_python_floor.py b/scripts/check_python_floor.py
index 0f7e45c8..4be7e1d3 100644
--- a/scripts/check_python_floor.py
+++ b/scripts/check_python_floor.py
@@ -41,10 +41,7 @@
     "node_modules",
 }
 
-DECLARATION_DOCS = (
-    Path("README.md"),
-    Path("spec/process/production-readiness.md"),
-)
+DECLARATION_DOCS = (Path("spec/process/production-readiness.md"),)
 
 
 def iter_python_files(paths: Iterable[Path]) -> list[Path]:
diff --git a/scripts/verify_local.py b/scripts/verify_local.py
index d904bf31..b00024e5 100644
--- a/scripts/verify_local.py
+++ b/scripts/verify_local.py
@@ -118,7 +118,7 @@ def _base_checks(
         ),
         Check(
             "examples",
-            "README/API examples and example-app checks",
+            "canonical API examples and example-app checks",
             (
                 py,
                 "-m",
@@ -146,7 +146,7 @@ def _base_checks(
                 "tests/test_scatter.py::test_to_html_escapes_user_strings",
                 "tests/test_components.py::test_component_to_html_escapes_user_strings_across_public_surface",
                 "tests/test_components.py::test_component_to_html_path_keeps_existing_file_on_atomic_replace_failure",
-                "tests/test_docs_examples.py::test_readme_documents_standalone_html_security_contract",
+                "tests/test_docs_examples.py::test_security_policy_documents_standalone_html_contract",
                 "tests/test_docs_examples.py::test_production_docs_capture_html_export_dom_text_contract",
             ),
             requires_modules=("pytest",),
diff --git a/spec/process/contributing.md b/spec/process/contributing.md
index c1f88f1f..f47df8cb 100644
--- a/spec/process/contributing.md
+++ b/spec/process/contributing.md
@@ -43,7 +43,7 @@ toolchain with `cargo`, `rustc`, and clippy for native-core checks. If clippy is
 missing, run `rustup component add clippy`. If you are only touching docs or
 pure Python shell code, `make check` is the fast non-JS/non-Rust gate.
 
-When README/API prose changes, run the focused docs gate:
+When canonical API prose or examples change, run the focused docs gate:
 
 ```bash
 make check-docs
@@ -96,15 +96,15 @@ regression comparison scripts, or report-schema validation, run:
 make check-benchmark-harness
 ```
 
-When you edit public docs, README text, package metadata, benchmark summaries,
-or anything that could become a public performance claim, run:
+When you edit public docs, package metadata, benchmark summaries, or anything
+that could become a public performance claim, run:
 
 ```bash
 make check-claims
 ```
 
-When you edit README snippets, `spec/api/api-examples.md`, or the Reflex example
-dashboard registry/assets, run:
+When you edit `spec/api/api-examples.md` or the Reflex example dashboard
+registry/assets, run:
 
 ```bash
 make check-examples
@@ -235,7 +235,7 @@ the `<CHROMIUM>` placeholder, name it explicitly, for example
   the patch; run `make check-security` for export/client text-sink changes.
 - Benchmarks label mode truthfully: `direct`, `decimated`, `density`, `sampled`,
   or `adaptive`.
-- README/docs examples still match the current public API.
+- Canonical API examples still match the current public API.
 - New public exports appear in `xy.__all__`, lazy `_EXPORTS`, and tests;
   run `make check-api` after public export or annotation changes.
 - Lazy import boundaries still keep package import light; run
diff --git a/spec/process/production-readiness.md b/spec/process/production-readiness.md
index b9f1605b..f5113cad 100644
--- a/spec/process/production-readiness.md
+++ b/spec/process/production-readiness.md
@@ -143,8 +143,8 @@ production-facing push:
 
 | Changed surface | Focused gate |
 |---|---|
-| README/API prose, examples, public benchmark wording | `make check-docs` |
-| README snippets, `spec/api/api-examples.md`, Reflex chart registry/assets | `make check-examples` |
+| API prose, examples, public benchmark wording | `make check-docs` |
+| `spec/api/api-examples.md`, Reflex chart registry/assets | `make check-examples` |
 | Public validation, error messages, builder rollback, LOD/drill mutation boundaries, chart/widget caching | `make check-errors` |
 | Public exports, lazy import mappings, component factories, public annotations | `make check-api` |
 | Import-time budget, `xy.__init__`, dependency boundaries, widget/export/backend import boundaries | `make check-import` |
@@ -166,8 +166,7 @@ Use this before pushing production-facing changes:
 make check-full
 ```
 
-Use this after editing README/API docs, example snippets, or public benchmark
-wording:
+Use this after editing API docs, example snippets, or public benchmark wording:
 
 ```bash
 make check-docs
@@ -224,8 +223,8 @@ verify those exact files rather than rebuilding locally:
 make check-artifacts SDIST=/path/to/xy.tar.gz WHEEL=/path/to/xy.whl
 ```
 
-Use this after editing README snippets, `spec/api/api-examples.md`, or the Reflex
-dashboard chart registry/assets:
+Use this after editing `spec/api/api-examples.md` or the Reflex dashboard chart
+registry/assets:
 
 ```bash
 make check-examples
@@ -275,8 +274,8 @@ tests:
 make check-benchmark-harness
 ```
 
-Use this after editing public docs, README text, package metadata, benchmark
-summaries, release notes, or other performance-claim surfaces:
+Use this after editing public docs, package metadata, benchmark summaries,
+release notes, or other performance-claim surfaces:
 
 ```bash
 make check-claims
@@ -371,7 +370,7 @@ Before tagging a release:
   package-only: docs, tests, benchmarks, scripts, and the `examples/` apps
   are sdist-only.
 - Confirm the wheel size budget is still below 15 MB.
-- Confirm README examples and `spec/api/api-examples.md` run against the tagged API.
+- Confirm `spec/api/api-examples.md` runs against the tagged API.
 - Confirm package metadata uses measured, scoped language rather than broad
   "faster/best" positioning.
 - Confirm performance claims mention chart type, mode, backend, data size, and
diff --git a/tests/test_docs_examples.py b/tests/test_docs_examples.py
index 1dd63f7f..39fd2c20 100644
--- a/tests/test_docs_examples.py
+++ b/tests/test_docs_examples.py
@@ -11,7 +11,6 @@
 ROOT = Path(__file__).resolve().parents[1]
 SPEC_DOCS = ROOT / "spec"
 API_EXAMPLES = SPEC_DOCS / "api" / "api-examples.md"
-README = ROOT / "README.md"
 CONTRIBUTING = ROOT / "CONTRIBUTING.md"
 SECURITY = ROOT / "SECURITY.md"
 BENCHMARK_DOC = SPEC_DOCS / "benchmarks" / "results.md"
@@ -135,52 +134,6 @@ def test_api_example_builds_payload(heading: str, source: str) -> None:
             assert isinstance(blob, bytes)
 
 
-@pytest.mark.parametrize(
-    ("heading", "source"), _python_examples(README), ids=lambda value: str(value)
-)
-def test_readme_python_example_runs(
-    heading: str,
-    source: str,
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    monkeypatch.chdir(tmp_path)
-    namespace: dict[str, object] = {"__name__": f"xy_readme_example_{heading}"}
-    uses_pyplot_show = source.rstrip().endswith("plt.show()")
-    if uses_pyplot_show:
-        import xy.pyplot as pyplot
-
-        monkeypatch.setattr(pyplot, "show", lambda *_args, **_kwargs: None)
-
-    exec(compile(_capture_final_expression(source), str(README), "exec"), namespace)
-
-    result = namespace.get("__example_result__")
-    if uses_pyplot_show and result is None:
-        result = namespace.get("fig")
-    assert result is not None, f"{heading} README example should end with an expression"
-    if isinstance(result, str):
-        assert "xy.renderStandalone" in result
-        if "chart.html" in source:
-            assert (tmp_path / "chart.html").read_text(encoding="utf-8") == result
-        return
-    if not hasattr(result, "figure") and not hasattr(result, "build_payload"):
-        # pyplot-shim figures display like notebooks display them.
-        html = result._repr_html_()
-        assert html.startswith('<iframe class="xy-notebook-frame"'), (
-            f"{heading} README example produced no chart"
-        )
-        assert 'sandbox="allow-scripts"' in html
-        assert "&lt;!doctype html&gt;" in html
-        assert "xy.renderStandalone" in html
-        return
-    figure = result.figure() if hasattr(result, "figure") else result
-    assert hasattr(figure, "build_payload"), f"{heading} README example did not produce a chart"
-    spec, blob = figure.build_payload()
-    json.dumps(spec, allow_nan=False)
-    assert spec["traces"], f"{heading} README example produced no traces"
-    assert isinstance(blob, bytes)
-
-
 def test_api_examples_cover_current_2d_surface() -> None:
     headings = {heading for heading, _source in _python_examples()}
     assert {
@@ -226,19 +179,6 @@ def test_api_examples_document_alpha_api_stability_boundary() -> None:
         assert marker in text
 
 
-def test_readme_documents_declarative_callback_serialization_boundary() -> None:
-    text = " ".join(README.read_text(encoding="utf-8").split())
-    required = [
-        "The composition contract we are locking is intentionally narrow and durable",
-        "opaque framework objects passed to `xy.legend(...)` / `xy.tooltip(...)`",
-        "without being serialized into standalone HTML",
-        "Python `on_*` callbacks stay widget-side",
-        "standalone HTML receives only the safe interaction flags",
-    ]
-    for marker in required:
-        assert marker in text
-
-
 def test_reflex_shaped_api_doc_tracks_locked_composition_contract() -> None:
     text = " ".join(REFLEX_SHAPED_API_DOC.read_text(encoding="utf-8").split())
     required = [
@@ -295,32 +235,6 @@ def test_security_policy_documents_standalone_html_contract() -> None:
         assert marker in text
 
 
-def test_readme_documents_stability_and_backend_contract() -> None:
-    text = " ".join(README.read_text(encoding="utf-8").split())
-    required = [
-        "Stable vs. Experimental",
-        "Stable enough to build on today",
-        "Still experimental and expected to change before 1.0",
-        "| Surface | Current status | Notes |",
-        "Stable alpha",
-        "Composition API",
-        "single public chart-building API",
-        "Stabilizing alpha",
-        "declarative `xy.chart(...children)`",
-        "CSS/Tailwind hooks",
-        "Reflex integration",
-        "Adaptive drilldown internals",
-        "Experimental",
-        "Python 3.11+ package import",
-        "Implemented 2D chart families",
-        "native Rust kernels",
-        "required compute core",
-        "raises a clear error rather than degrading",
-    ]
-    for marker in required:
-        assert marker in text
-
-
 def test_contributing_documents_backend_check() -> None:
     text = " ".join(CONTRIBUTING.read_text(encoding="utf-8").split())
     required = [
@@ -336,58 +250,6 @@ def test_contributing_documents_backend_check() -> None:
         assert marker in text
 
 
-def test_readme_documents_install_paths() -> None:
-    text = " ".join(README.read_text(encoding="utf-8").split())
-    required = [
-        "uv add xy",
-        "Published wheels contain the Python package, JavaScript client, and native Rust core",
-        "End users do not need Rust, Node, npm, or a CDN",
-    ]
-    for marker in required:
-        assert marker in text
-    assert "Install/backend quick matrix" not in text
-
-
-def test_readme_getting_started_includes_small_business_chart() -> None:
-    text = " ".join(README.read_text(encoding="utf-8").split())
-    required = [
-        "Create a small business chart",
-        "Revenue vs pipeline",
-        "USD thousands",
-        "xy.line(months, revenue",
-        "xy.line(months, pipeline",
-    ]
-    for marker in required:
-        assert marker in text
-
-
-def test_readme_architecture_diagram_covers_major_boundaries() -> None:
-    text = " ".join(README.read_text(encoding="utf-8").split())
-    required = [
-        "```mermaid",
-        "Python kernel / app process",
-        "User APIs",
-        "ColumnStore",
-        "rollback checkpoints",
-        "Compute core",
-        "native Rust C ABI",
-        "(required; no fallback)",
-        "Payload builder",
-        "Browser / notebook frontend",
-        "WebGL2 renderer",
-        "DOM chrome",
-        "Interaction layer",
-        "Adaptive large-data loop",
-        "direct, decimated",
-        "density, adaptive",
-        "spec JSON + typed buffers",
-        "no JSON number arrays",
-        "new screen-bounded payload",
-    ]
-    for marker in required:
-        assert marker in text
-
-
 def test_benchmark_docs_name_ci_report_artifacts() -> None:
     text = " ".join(BENCHMARK_DOC.read_text(encoding="utf-8").split())
     required = [
@@ -423,35 +285,33 @@ def test_benchmark_docs_include_copyable_claim_taxonomy() -> None:
 
 
 def test_docs_name_benchmark_harness_shortcut() -> None:
-    readme = " ".join(README.read_text(encoding="utf-8").split())
     production = " ".join(PRODUCTION_DOC.read_text(encoding="utf-8").split())
     contributing = " ".join(
         (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8").split()
     )
 
-    for text in (readme, production, contributing):
+    for text in (production, contributing):
         assert "make check-benchmark-harness" in text
-    assert "environment metadata" in readme
+    assert "environment metadata" in contributing
     assert "report-schema validation" in production
     assert "regression comparison scripts" in contributing
 
 
 def test_docs_name_claim_guardrail_shortcut() -> None:
-    readme = " ".join(README.read_text(encoding="utf-8").split())
     production = " ".join(PRODUCTION_DOC.read_text(encoding="utf-8").split())
     contributing = " ".join(
         (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8").split()
     )
 
-    for text in (readme, production, contributing):
+    for text in (production, contributing):
         assert "make check-claims" in text
         assert "make check-docs" in text
     assert "Claim guardrails" in production
     assert (
         "Public docs and package metadata avoid broad, unqualified performance claims" in production
     )
-    assert "README/API docs, example snippets, or public benchmark wording" in production
-    assert "public-facing text" in readme
+    assert "API docs, example snippets, or public benchmark wording" in production
+    assert "public performance claim" in contributing
 
 
 def test_production_docs_include_focused_gate_matrix() -> None:
@@ -459,7 +319,7 @@ def test_production_docs_include_focused_gate_matrix() -> None:
     required = [
         "Changed surface",
         "Focused gate",
-        "README/API prose, examples, public benchmark wording",
+        "API prose, examples, public benchmark wording",
         "`make check-docs`",
         "Public validation, error messages, builder rollback, LOD/drill mutation boundaries, chart/widget caching",
         "`make check-errors`",
@@ -497,7 +357,6 @@ def test_production_docs_name_ci_workflow_gate_shortcut() -> None:
 
 
 def test_docs_name_split_browser_hardening_gates() -> None:
-    readme = " ".join(README.read_text(encoding="utf-8").split())
     production = " ".join(PRODUCTION_DOC.read_text(encoding="utf-8").split())
     contributing = " ".join(
         (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8").split()
@@ -513,7 +372,7 @@ def test_docs_name_split_browser_hardening_gates() -> None:
         "scripts/visual_regression_smoke.py",
         "scripts/interaction_stress_smoke.py",
     ]
-    for text in (readme, production, contributing):
+    for text in (production, contributing):
         assert "make check-browser" in text
         for step_name in step_names:
             assert step_name in text
diff --git a/tests/test_python_floor.py b/tests/test_python_floor.py
index 08ea4d11..75e9cd0a 100644
--- a/tests/test_python_floor.py
+++ b/tests/test_python_floor.py
@@ -23,7 +23,6 @@ def _write_floor_repo(
     *,
     requires_python: str = ">=3.11",
     ruff_target: str = "py311",
-    readme: str = "Install with Python 3.11+.\n",
     production_readiness: str = "The current contract is Python 3.11+ only.\n",
 ) -> None:
     root.joinpath("spec", "process").mkdir(parents=True)
@@ -35,7 +34,6 @@ def _write_floor_repo(
         f'target-version = "{ruff_target}"\n',
         encoding="utf-8",
     )
-    root.joinpath("README.md").write_text(readme, encoding="utf-8")
     root.joinpath("spec", "process", "production-readiness.md").write_text(
         production_readiness,
         encoding="utf-8",
@@ -65,11 +63,11 @@ def test_python_floor_rejects_mismatched_ruff_target(tmp_path: Path) -> None:
 
 
 def test_python_floor_rejects_missing_docs_floor(tmp_path: Path) -> None:
-    _write_floor_repo(tmp_path, readme="Install with Python.\n")
+    _write_floor_repo(tmp_path, production_readiness="The current contract is Python only.\n")
 
     errors = check_python_floor.check_declared_floor(tmp_path)
 
-    assert any("README.md" in error and "Python 3.11+" in error for error in errors)
+    assert any("production-readiness.md" in error and "Python 3.11+" in error for error in errors)
 
 
 def test_python_floor_accepts_annotated_file_with_future_annotations(tmp_path: Path) -> None:
diff --git a/tests/test_verify_local.py b/tests/test_verify_local.py
index 4772687f..909816e3 100644
--- a/tests/test_verify_local.py
+++ b/tests/test_verify_local.py
@@ -481,7 +481,6 @@ def test_contributor_setup_builds_native_core_and_docs_use_it() -> None:
     contributor_docs = (
         (ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8"),
         (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8"),
-        (ROOT / "README.md").read_text(encoding="utf-8"),
         (ROOT / "docs" / "api-reference" / "contributing.md").read_text(encoding="utf-8"),
     )
     for text in contributor_docs:
@@ -608,9 +607,8 @@ def test_makefile_exposes_claim_guardrail_shortcut() -> None:
 def test_contributor_docs_name_full_gate_toolchain_requirements() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "Node 18+" in text
         assert "cargo" in text
         assert "rustc" in text
@@ -620,9 +618,8 @@ def test_contributor_docs_name_full_gate_toolchain_requirements() -> None:
 def test_docs_name_example_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-examples" in text
     assert "spec/api/api-examples.md" in contributing
     assert "Reflex example" in contributing
@@ -631,104 +628,93 @@ def test_docs_name_example_verification_shortcut() -> None:
 def test_docs_name_docs_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
     production_inline = " ".join(production.split())
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-docs" in text
-    assert "README/API prose" in contributing
+    assert "API prose" in contributing
     assert "public benchmark wording" in production_inline
-    assert "README/API prose" in readme
 
 
 def test_docs_name_security_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-security" in text
     assert "standalone HTML export" in contributing
     assert "browser client DOM" in production
-    assert "browser client text" in readme
+    assert "browser client text-node insertion" in production
 
 
 def test_docs_name_error_safety_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-errors" in text
     assert "builder rollback behavior" in contributing
     assert "LOD/drill mutation boundaries" in contributing
     assert "chart/widget caching" in production
     assert "LOD/drill mutation boundaries" in production
-    assert "public errors" in readme
-    assert "LOD/drill mutation boundaries" in readme
+    assert "public errors" in contributing
 
 
 def test_docs_name_api_surface_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
-    readme_inline = " ".join(readme.split())
+    production_inline = " ".join(production.split())
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-api" in text
     assert "public export" in contributing
     assert "lazy import mappings" in production
-    assert "public annotations" in readme_inline
+    assert "public annotations" in production_inline
 
 
 def test_docs_name_import_budget_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-import" in text
         assert "lazy import" in text
         assert "dependency boundaries" in text
     assert "xy.__init__" in contributing
-    assert "widget/export boundaries" in readme
+    assert "widget/export boundaries" in contributing
     assert "backend import boundaries" in production
 
 
 def test_docs_name_ci_workflow_verification_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-ci" in text
     assert ".github/workflows/ci.yml" in contributing
     assert "trusted publishing" in production
-    assert "benchmark artifact wiring" in readme
+    assert "benchmark artifact wiring" in contributing
 
 
 def test_docs_name_claim_guardrail_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-claims" in text
     assert "public performance claim" in contributing
     assert "performance-claim surfaces" in production
-    assert "public-facing text" in readme
 
 
 def test_docs_name_benchmark_harness_shortcut() -> None:
     contributing = (SPEC_DOCS / "process" / "contributing.md").read_text(encoding="utf-8")
     production = (SPEC_DOCS / "process" / "production-readiness.md").read_text(encoding="utf-8")
-    readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
-    for text in (contributing, production, readme):
+    for text in (contributing, production):
         assert "make check-benchmark-harness" in text
     assert "benchmark environment metadata" in contributing
     assert "report-schema validation" in production
-    assert "regression comparison scripts" in readme
+    assert "regression comparison scripts" in contributing
 
 
 def test_node_version_parser_accepts_v_prefixed_versions() -> None:
diff --git a/tests/test_verify_sdist.py b/tests/test_verify_sdist.py
index f8daecfc..c500465a 100644
--- a/tests/test_verify_sdist.py
+++ b/tests/test_verify_sdist.py
@@ -59,7 +59,7 @@
     "## Pull Request Checklist\n\n"
     "Run make check-full, make check-sdist, make check-wheel, and "
     "make check-benchmark-report.\n"
-    "Run make check-examples for README snippets, spec/api/api-examples.md, and "
+    "Run make check-examples for spec/api/api-examples.md and "
     "the example apps.\n\n"
     "## Performance Claims\n\n"
     "Claims need benchmark context.\n" + ("contributing padding\n" * 100)

From 0c3109d745ac06d2577725eb6b420cb3f485026f Mon Sep 17 00:00:00 2001
From: Alek <alek@reflex.dev>
Date: Thu, 23 Jul 2026 16:13:46 -0700
Subject: [PATCH 2/2] Remove remaining README test dependencies

---
 scripts/check_claim_guardrails.py   |  2 --
 scripts/verify_sdist.py             | 17 ------------
 spec/benchmarks/results.md          |  6 ++---
 tests/test_benchmark_environment.py |  7 +----
 tests/test_claim_guardrails.py      |  2 +-
 tests/test_docs_examples.py         |  2 +-
 tests/test_verify_sdist.py          | 41 +----------------------------
 7 files changed, 7 insertions(+), 70 deletions(-)

diff --git a/scripts/check_claim_guardrails.py b/scripts/check_claim_guardrails.py
index 4f51afc3..47a133e2 100644
--- a/scripts/check_claim_guardrails.py
+++ b/scripts/check_claim_guardrails.py
@@ -25,8 +25,6 @@
     "spec/api/chart-roadmap.md",
     "spec/process/contributing.md",
     "spec/process/production-readiness.md",
-    "examples/reflex/README.md",
-    "examples/fastapi/README.md",
 )
 
 BROAD_SUPERLATIVE_RE = re.compile(
diff --git a/scripts/verify_sdist.py b/scripts/verify_sdist.py
index a991db75..ae7640bb 100644
--- a/scripts/verify_sdist.py
+++ b/scripts/verify_sdist.py
@@ -34,10 +34,8 @@
     "LICENSE",
     "Makefile",
     "PKG-INFO",
-    "README.md",
     "SECURITY.md",
     "benchmarks/__init__.py",
-    "benchmarks/README.md",
     "benchmarks/_browser.py",
     "benchmarks/_xy_browser.py",
     "benchmarks/baseline.json",
@@ -54,7 +52,6 @@
     "benchmarks/bench_workflows.py",
     "benchmarks/categories.py",
     "benchmarks/environment.py",
-    "spec/README.md",
     "spec/design-dossier.md",
     "spec/api/api-examples.md",
     "spec/api/chart-roadmap.md",
@@ -97,12 +94,10 @@
     "python/xy/static/index.js",
     "python/xy/static/standalone.js",
     "python/xy/widget.py",
-    "examples/fastapi/README.md",
     "examples/fastapi/pyproject.toml",
     "examples/fastapi/app.py",
     "examples/fastapi/charts.py",
     "examples/fastapi/live_drilldown.py",
-    "examples/reflex/README.md",
     "examples/reflex/pyproject.toml",
     "examples/reflex/rxconfig.py",
     "examples/reflex/xy_reflex_demo/__init__.py",
@@ -409,18 +404,6 @@ def verify_sdist(path: str) -> None:
             "Performance Claims",
         },
     )
-    _require_file_contains(
-        path,
-        root,
-        "examples/reflex/README.md",
-        {"reflex-xy showcase", "reflex run", "reflex_xy.XYPlugin()"},
-    )
-    _require_file_contains(
-        path,
-        root,
-        "examples/fastapi/README.md",
-        {"FastAPI", "chart.to_html()", "/api/xy/drilldown"},
-    )
     _require_file_contains(
         path,
         root,
diff --git a/spec/benchmarks/results.md b/spec/benchmarks/results.md
index 20112565..6b04b3b7 100644
--- a/spec/benchmarks/results.md
+++ b/spec/benchmarks/results.md
@@ -188,9 +188,9 @@ environment metadata and benchmark category IDs.
 
 ## Copyable claim taxonomy
 
-Use these shapes when turning benchmark rows into README text, release notes, or
-posts. The goal is to make every public claim reproducible from a row in this
-document or from a verified JSON artifact.
+Use these shapes when turning benchmark rows into public prose, release notes,
+or posts. The goal is to make every public claim reproducible from a row in
+this document or from a verified JSON artifact.
 
 | Claim shape | Safe wording pattern | Required context |
 |---|---|---|
diff --git a/tests/test_benchmark_environment.py b/tests/test_benchmark_environment.py
index b4f5130e..b1aa799e 100644
--- a/tests/test_benchmark_environment.py
+++ b/tests/test_benchmark_environment.py
@@ -158,16 +158,13 @@ def test_codspeed_animation_module_guards_backend_and_split_transport() -> None:
     assert "build_payload_split" in source
 
 
-def test_codspeed_dependency_is_declared_and_shared_by_ci_and_runbook() -> None:
+def test_codspeed_dependency_is_declared_and_used_by_ci() -> None:
     pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
     workflow = (ROOT / ".github" / "workflows" / "codspeed.yml").read_text(encoding="utf-8")
-    runbook = (ROOT / "benchmarks" / "README.md").read_text(encoding="utf-8")
 
     assert "codspeed = [" in pyproject
     assert '"pytest-codspeed>=5,<6"' in pyproject
     assert '-e ".[dev,codspeed]"' in workflow
-    assert '-e ".[dev,codspeed]"' in runbook
-    assert "--codspeed" in runbook
 
 
 def test_native_benchmark_reports_can_resolve_source_backend_metadata() -> None:
@@ -182,12 +179,10 @@ def test_native_benchmark_reports_can_resolve_source_backend_metadata() -> None:
 
 def test_scatter_native_exposes_reproducible_categorical_ceiling() -> None:
     source = (ROOT / "benchmarks" / "bench_scatter_native.py").read_text(encoding="utf-8")
-    runbook = (ROOT / "benchmarks" / "README.md").read_text(encoding="utf-8")
     assert "def gen_numpy_categories" in source
     assert "def _warm_production_path" in source
     assert '"--categorical-groups"' in source
     assert '"categorical_groups"' in source
-    assert "--categorical-groups 24" in runbook
 
 
 def test_interaction_browser_gates_cover_scatter_and_core_chart_families() -> None:
diff --git a/tests/test_claim_guardrails.py b/tests/test_claim_guardrails.py
index b189d219..ed6fd4ed 100644
--- a/tests/test_claim_guardrails.py
+++ b/tests/test_claim_guardrails.py
@@ -30,7 +30,7 @@ def test_claim_guardrail_accepts_current_public_docs() -> None:
     assert findings == []
     assert check_claim_guardrails.ROOT / "pyproject.toml" in check_claim_guardrails._default_paths()
     assert (
-        check_claim_guardrails.ROOT / "examples" / "reflex" / "README.md"
+        check_claim_guardrails.ROOT / "spec" / "benchmarks" / "results.md"
         in check_claim_guardrails._default_paths()
     )
     assert (
diff --git a/tests/test_docs_examples.py b/tests/test_docs_examples.py
index 39fd2c20..d8267d16 100644
--- a/tests/test_docs_examples.py
+++ b/tests/test_docs_examples.py
@@ -271,7 +271,7 @@ def test_benchmark_docs_include_copyable_claim_taxonomy() -> None:
     text = " ".join(BENCHMARK_DOC.read_text(encoding="utf-8").split())
     required = [
         "Copyable claim taxonomy",
-        "Use these shapes when turning benchmark rows into README text",
+        "Use these shapes when turning benchmark rows into public prose",
         "Payload/prep comparison",
         "Browser first paint",
         "Large scatter overview",
diff --git a/tests/test_verify_sdist.py b/tests/test_verify_sdist.py
index c500465a..7ddb8666 100644
--- a/tests/test_verify_sdist.py
+++ b/tests/test_verify_sdist.py
@@ -27,7 +27,6 @@
     "const padding = '" + ("x" * 1000) + "';\n"
     "export default { render, decodeFrame };\n"
 )
-README_MD = "# XY\n" + ("README fixture\n" * 100)
 API_EXAMPLES_MD = (
     "# API Examples\n\n"
     "## Chart Family Quick Reference\n\n"
@@ -64,16 +63,6 @@
     "## Performance Claims\n\n"
     "Claims need benchmark context.\n" + ("contributing padding\n" * 100)
 )
-REFLEX_README_MD = (
-    "# reflex-xy showcase\n\n"
-    "Wired with reflex_xy.XYPlugin() in rxconfig.py; run with reflex run.\n"
-    + ("reflex readme padding\n" * 100)
-)
-FASTAPI_README_MD = (
-    "# xy FastAPI example\n\n"
-    "A FastAPI app that generates charts with chart.to_html() and serves a "
-    "live drilldown via POST /api/xy/drilldown.\n" + ("fastapi readme padding\n" * 100)
-)
 CI_YML = (
     "name: CI\n"
     "jobs:\n"
@@ -168,8 +157,6 @@ def _write_sdist(
                 data = STANDALONE_JS.encode("utf-8")
             elif name == "js/src/60_entries.ts":
                 data = ENTRIES_JS.encode("utf-8")
-            elif name == "README.md":
-                data = README_MD.encode("utf-8")
             elif name == "spec/api/api-examples.md":
                 data = API_EXAMPLES_MD.encode("utf-8")
             elif name == "spec/benchmarks/results.md":
@@ -178,10 +165,6 @@ def _write_sdist(
                 data = PRODUCTION_READINESS_MD.encode("utf-8")
             elif name == "spec/process/contributing.md":
                 data = CONTRIBUTING_MD.encode("utf-8")
-            elif name == "examples/reflex/README.md":
-                data = REFLEX_README_MD.encode("utf-8")
-            elif name == "examples/fastapi/README.md":
-                data = FASTAPI_README_MD.encode("utf-8")
             elif name == ".github/workflows/ci.yml":
                 data = CI_YML.encode("utf-8")
             elif name == ".github/workflows/codspeed.yml":
@@ -434,28 +417,6 @@ def test_verify_sdist_rejects_stale_contributing_doc(tmp_path: Path) -> None:
         verify_sdist.verify_sdist(str(sdist))
 
 
-def test_verify_sdist_rejects_stale_reflex_example_readme(tmp_path: Path) -> None:
-    sdist = tmp_path / "xy-0.0.1.tar.gz"
-    _write_sdist(
-        sdist,
-        replacements={"examples/reflex/README.md": "# Reflex\n" + ("padding\n" * 200)},
-    )
-
-    with pytest.raises(AssertionError, match="examples/reflex/README"):
-        verify_sdist.verify_sdist(str(sdist))
-
-
-def test_verify_sdist_rejects_stale_fastapi_example_readme(tmp_path: Path) -> None:
-    sdist = tmp_path / "xy-0.0.1.tar.gz"
-    _write_sdist(
-        sdist,
-        replacements={"examples/fastapi/README.md": "# FastAPI\n" + ("padding\n" * 200)},
-    )
-
-    with pytest.raises(AssertionError, match="examples/fastapi/README"):
-        verify_sdist.verify_sdist(str(sdist))
-
-
 def test_verify_sdist_rejects_missing_release_workflow(tmp_path: Path) -> None:
     sdist = tmp_path / "xy-0.0.1.tar.gz"
     _write_sdist(sdist, omit={".github/workflows/release.yml"})
@@ -529,7 +490,7 @@ def test_verify_sdist_rejects_generated_artifacts(tmp_path: Path, artifact: str)
 
 def test_verify_sdist_rejects_duplicate_file_member(tmp_path: Path) -> None:
     sdist = tmp_path / "xy-0.0.1.tar.gz"
-    _write_sdist(sdist, extra={"README.md": b"duplicate"})
+    _write_sdist(sdist, extra={"LICENSE": b"duplicate"})
 
     with pytest.raises(AssertionError, match="duplicate file member"):
         verify_sdist.verify_sdist(str(sdist))