diff --git a/README.md b/README.md
index d0e79f6..e84331a 100644
--- a/README.md
+++ b/README.md
@@ -208,6 +208,8 @@ Omitting `doc_ids` queries the **entire collection** and lets the agent pick whi
 
 - [`examples/local_demo.py`](examples/local_demo.py) — local mode end-to-end (index a PDF + streaming QA)
 - [`examples/cloud_demo.py`](examples/cloud_demo.py) — cloud mode end-to-end
+- [`examples/demo_query_modes.py`](examples/demo_query_modes.py) — exercises all `Collection.query` modes (single / multi / scoped / experimental warning)
+- [`examples/demo_legacy_sdk.py`](examples/demo_legacy_sdk.py) — smoke test for the legacy `pageindex_sdk` 0.2.x compatibility layer against the cloud API
 - [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py) — lower-level integration with the OpenAI Agents SDK
 
 ---
diff --git a/scripts/e2e_legacy_sdk.py b/examples/demo_legacy_sdk.py
similarity index 92%
rename from scripts/e2e_legacy_sdk.py
rename to examples/demo_legacy_sdk.py
index 7d805e5..707893d 100644
--- a/scripts/e2e_legacy_sdk.py
+++ b/examples/demo_legacy_sdk.py
@@ -1,6 +1,10 @@
 """End-to-end smoke test of the legacy SDK compatibility layer against the real cloud API.
 
-Run: PAGEINDEX_API_KEY=... uv run python scripts/e2e_legacy_sdk.py
+Exercises the legacy `pageindex_sdk` 0.2.x methods preserved on `PageIndexClient`:
+submit_document, is_retrieval_ready, get_tree, get_document, chat_completions
+(sync + stream), and delete_document.
+
+Run: PAGEINDEX_API_KEY=... python examples/demo_legacy_sdk.py
 """
 from __future__ import annotations
 import os