wave9: migrate docs and demos to async Client release prep

Author: GSstarGamer

README.md

@@ -4,8 +4,8 @@ Py-Ritone is a zero-setup local bridge between a Fabric Minecraft client (with B
 
 ## Monorepo Layout
 
-- `mod/`: Fabric client mod (`pyritone_bridge`) exposing a local NDJSON socket bridge.
-- `python/`: PyPI-ready package (`pyritone`) with async client, sync wrapper, and CLI.
+- `mod/`: Fabric client mod (`pyritone_bridge`) exposing a local WebSocket v2 bridge.
+- `python/`: PyPI-ready package (`pyritone`) with async client, compatibility aliases, and CLI.
 - `protocol/`: Versioned bridge protocol docs and JSON schema.
 - `docs/`: Developer setup and runbook.
 
@@ -20,16 +20,22 @@ Py-Ritone is a zero-setup local bridge between a Fabric Minecraft client (with B
 pip install pyritone
 ```
 
-5. Start Minecraft client. Py-Ritone opens `127.0.0.1:27841` automatically.
+5. Start Minecraft client. Py-Ritone opens the local bridge at `ws://127.0.0.1:27841/ws` automatically.
 6. Use the package:
 
 ```python
-from pyritone import PyritoneClient
+import asyncio
+from pyritone import Client
 
-with PyritoneClient() as client:
-    print(client.ping())
-    print(client.status_get())
-    print(client.execute("goto 100 70 100"))
+
+async def main() -> None:
+    async with Client() as client:
+        print(await client.ping())
+        print(await client.status_get())
+        print(await client.execute("goto 100 70 100"))
+
+
+asyncio.run(main())
 ```
 
 ## Demos / Videos
@@ -58,6 +64,11 @@ python demos/01_connect_discovery.py
   - `09` local-path build helper: `python demos/09_build_file_local_path.py "house.schem" --coords 100 -60 100 --wait`
   - `10` CLI entrypoints: `python demos/10_cli_entrypoints.py`
 
+## Release Prep
+
+- Async-only release checklist: `docs/release-checklist.md`
+- Parity/fallback debt snapshot: `python/docs/release-parity-fallback-report.md`
+
 ## One-Click Dev Client
 
 - Double-click `run_dev_client.bat` at repo root, or run it in terminal:

docs/dev-setup.md

@@ -39,9 +39,15 @@ python -m twine check dist/*
 3. From Python:
 
 ```python
-from pyritone import PyritoneClient
+import asyncio
+from pyritone import Client
 
-with PyritoneClient() as client:
-    print(client.ping())
-    print(client.status_get())
+
+async def main() -> None:
+    async with Client() as client:
+        print(await client.ping())
+        print(await client.status_get())
+
+
+asyncio.run(main())
 ```

docs/release-checklist.md

@@ -0,0 +1,39 @@
+# Release Checklist (Async-Only Client Era)
+
+Use this checklist before publishing a release from `feat/ws-v2-async`.
+
+## 1. Quality Gates
+
+- `python -m pytest -q`
+- `cd mod && .\gradlew.bat test --no-daemon`
+- `python python/tools/generate_baritone_commands.py --check`
+
+## 2. Documentation Gates
+
+- Root docs show `pyritone.Client` as the primary client.
+- Python docs/examples are async-only (`await` + `async with Client()` flows).
+- Demo scripts run with async client helpers.
+- Migration notes are confined to:
+  - `python/docs/migration-from-legacy-aliases.md`
+
+## 3. Parity + Debt Review
+
+- Confirm typed parity matrix is current:
+  - `python/docs/baritone-typed-parity.md`
+- Confirm release parity/debt snapshot is current:
+  - `python/docs/release-parity-fallback-report.md`
+- Confirm fallback debt gates are green:
+  - `python/tests/test_fallback_debt.py`
+
+## 4. Versioning + Changelog
+
+- Record user-facing changes in changelog under an `Unreleased` (or release) section.
+- If compatibility aliases/shims are removed, treat as a breaking change release.
+- Ensure release notes call out websocket v2 + async-only client direction.
+
+## 5. Publish Readiness
+
+- Build Python package:
+  - `cd python && python -m build`
+  - `cd python && python -m twine check dist/*`
+- Validate release artifacts and docs links before tagging.

docs/runbook.md

@@ -1,5 +1,10 @@
 # Runbook
 
+## Release Prep
+
+- Async-only release checklist: `docs/release-checklist.md`
+- Parity/fallback debt snapshot: `python/docs/release-parity-fallback-report.md`
+
 ## Bridge Not Starting
 
 - Check Minecraft client logs for `pyritone_bridge` startup errors.

python/README.md

@@ -50,6 +50,7 @@ python demos/01_connect_discovery.py
 - Full docs index: `python/docs/index.md`
 - Quickstart: `python/docs/quickstart.md`
 - Async client guide: `python/docs/async-client.md`
+- Legacy import migration: `python/docs/migration-from-legacy-aliases.md`
 - Settings API: `python/docs/settings-api.md`
 - Tasks/events/waiting: `python/docs/tasks-events-and-waiting.md`
 - Errors/troubleshooting: `python/docs/errors-and-troubleshooting.md`
@@ -64,14 +65,13 @@ python demos/01_connect_discovery.py
   - `python/docs/commands/aliases.md`
 - Raw Baritone appendix: `python/docs/baritone-commands.md`
 - Typed parity matrix: `python/docs/baritone-typed-parity.md`
+- Release parity/debt report: `python/docs/release-parity-fallback-report.md`
 
 ## Public API Map
 
 - Clients:
-  - `Client` (primary)
-  - `PyritoneClient`
-  - `AsyncPyritoneClient`
-  - `PyritoneClient` and `AsyncPyritoneClient` are temporary async aliases of `Client`.
+  - `Client` (primary async surface)
+  - Legacy aliases (`PyritoneClient`, `AsyncPyritoneClient`) are compatibility-only; use `Client` in docs and new code.
 - Low-level methods:
   - `ping`, `status_get`, `status_subscribe`, `status_unsubscribe`, `execute`, `cancel`, `next_event`, `wait_for`, `wait_for_task`
   - Typed API substrate: `api_metadata_get`, `api_construct`, `api_invoke`

python/demos/01_connect_discovery.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from _common import print_json, run_sync_demo, step
+from _common import print_json, run_async_demo, step
 
 
-def demo(client):
+async def demo(client):
     step("Using default discovery: bridge-info file or PYRITONE_* overrides.")
-    print_json("ping()", client.ping())
-    print_json("status_get()", client.status_get())
+    print_json("ping()", await client.ping())
+    print_json("status_get()", await client.status_get())
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(run_sync_demo("01 - Connect + Discovery", demo))
+    raise SystemExit(run_async_demo("01 - Connect + Discovery", demo))

python/demos/02_basic_commands.py

@@ -1,27 +1,27 @@
 from __future__ import annotations
 
-from _common import print_json, run_sync_demo, step, summarize_dispatch
+from _common import print_json, run_async_demo, step, summarize_dispatch
 
 
-def demo(client):
+async def demo(client):
     step("High-level wrappers first: help(), version(), set(...).")
 
-    help_dispatch = client.help()
+    help_dispatch = await client.help()
     print(f"help() summary: {summarize_dispatch(help_dispatch)}")
     print_json("help()", help_dispatch)
 
-    version_dispatch = client.version()
+    version_dispatch = await client.version()
     print(f"version() summary: {summarize_dispatch(version_dispatch)}")
     print_json("version()", version_dispatch)
 
-    set_dispatch = client.set("allowPlace", True)
+    set_dispatch = await client.set("allowPlace", True)
     print(f"set('allowPlace', True) summary: {summarize_dispatch(set_dispatch)}")
     print_json("set('allowPlace', True)", set_dispatch)
 
-    step("Raw fallback: execute('help').")
-    print_json("execute('help')", client.execute("help"))
+    step("Raw command transport: execute('help').")
+    print_json("execute('help')", await client.execute("help"))
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(run_sync_demo("02 - Basic Commands", demo))
+    raise SystemExit(run_async_demo("02 - Basic Commands", demo))

python/demos/03_goto_completion.py

@@ -4,7 +4,7 @@
 
 from _common import (
     print_json,
-    run_sync_demo,
+    run_async_demo,
     step,
     summarize_pause_update,
     summarize_dispatch,
@@ -21,9 +21,9 @@
 args = parser.parse_args()
 
 
-def demo(client):
+async def demo(client):
     step(f"Dispatching goto({args.x}, {args.y}, {args.z})")
-    dispatch = client.goto(args.x, args.y, args.z)
+    dispatch = await client.goto(args.x, args.y, args.z)
     print(f"goto dispatch summary: {summarize_dispatch(dispatch)}")
     print_json("goto dispatch", dispatch)
 
@@ -58,12 +58,12 @@ def on_update(event):
             print(f"task update: {line}")
             last_line = line
 
-    terminal_event = client.wait_for_task(task_id, on_update=on_update)
+    terminal_event = await client.wait_for_task(task_id, on_update=on_update)
     print(f"terminal event summary: {summarize_event(terminal_event)}")
     print_json("terminal event", terminal_event)
     step(terminal_summary(terminal_event))
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(run_sync_demo("03 - Goto + Completion", demo))
+    raise SystemExit(run_async_demo("03 - Goto + Completion", demo))

python/demos/04_live_event_feed.py

@@ -2,7 +2,7 @@
 
 import argparse
 
-from _common import run_sync_demo, step, task_reason
+from _common import run_async_demo, step, task_reason
 
 
 parser = argparse.ArgumentParser(description="Dispatch demo goto and print concise live bridge events")
@@ -71,11 +71,11 @@ def _event_line(index: int, event: dict) -> str:
     )
 
 
-def demo(client):
+async def demo(client):
     step(
         "Dispatching demo goto to an intentionally high Y so recording clearly shows live path/task behavior."
     )
-    dispatch = client.goto(args.x, args.y, args.z)
+    dispatch = await client.goto(args.x, args.y, args.z)
     task_id = dispatch.get("task_id")
     accepted = dispatch.get("accepted")
     print(
@@ -94,7 +94,7 @@ def demo(client):
 
     while args.max_events <= 0 or displayed < args.max_events:
         try:
-            event = client.next_event(timeout=args.timeout)
+            event = await client.next_event(timeout=args.timeout)
         except TimeoutError:
             step(f"No event in {args.timeout:.1f}s window; still listening...")
             continue
@@ -145,4 +145,4 @@ def demo(client):
 
 
 if __name__ == "__main__":
-    raise SystemExit(run_sync_demo("04 - Live Event Feed", demo))
+    raise SystemExit(run_async_demo("04 - Live Event Feed", demo))

python/demos/05_cancel_task.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import argparse
-import time
+import asyncio
 
 from _common import (
     print_json,
-    run_sync_demo,
+    run_async_demo,
     step,
     summarize_dispatch,
     summarize_event,
@@ -18,31 +18,31 @@
 args = parser.parse_args()
 
 
-def demo(client):
+async def demo(client):
     step("Starting a long-running task with high-level wrapper: explore()")
-    dispatch = client.explore()
+    dispatch = await client.explore()
     print(f"explore() dispatch summary: {summarize_dispatch(dispatch)}")
     print_json("explore() dispatch", dispatch)
 
     task_id = dispatch.get("task_id")
     if not task_id:
         step("No task_id returned, cannot target a specific cancel. Sending global cancel instead.")
-        print_json("cancel()", client.cancel())
+        print_json("cancel()", await client.cancel())
         return 0
 
     step(f"Waiting {args.delay:.1f}s before canceling task_id={task_id}")
-    time.sleep(max(args.delay, 0.0))
+    await asyncio.sleep(max(args.delay, 0.0))
 
-    cancel_result = client.cancel(task_id=task_id)
+    cancel_result = await client.cancel(task_id=task_id)
     print_json("cancel(task_id)", cancel_result)
 
     step("Waiting for terminal task event after cancel")
-    terminal_event = client.wait_for_task(task_id)
+    terminal_event = await client.wait_for_task(task_id)
     print(f"terminal event summary: {summarize_event(terminal_event)}")
     print_json("terminal event", terminal_event)
     step(terminal_summary(terminal_event))
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(run_sync_demo("05 - Cancel Task", demo))
+    raise SystemExit(run_async_demo("05 - Cancel Task", demo))