Decouple CI tests from README

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' \

scripts/check_claim_guardrails.py

@@ -18,16 +18,13 @@
 ROOT = Path(__file__).resolve().parents[1]
 DEFAULT_DOCS = (
     "pyproject.toml",
-    "README.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "spec/api/api-examples.md",
     "spec/benchmarks/results.md",
     "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(

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]:

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",
@@ -408,18 +403,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,

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 |
 |---|---|---|

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

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

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:

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"
@@ -59,21 +58,11 @@
     "## 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)
 )
-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":
@@ -426,28 +409,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"})
@@ -521,7 +482,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))