scripts: run_demo.sh launcher (no python on PATH needed), friendly port-in-use check in run_bridge.sh; README updated

testbed/README.md

@@ -27,38 +27,43 @@ over the protocol, no engine hooks.
 
 ```bash
 scripts/setup.sh                 # venv + aicc-py + pillow/websockets/openai
-source testbed/.venv/bin/activate
 ```
 
 The testbed needs the `aicc` SDK installed from `~/Desktop/aicc-py` (the setup
-script does `pip install -e`).
+script does `pip install -e`). The launcher scripts below use the venv
+interpreter directly, so `python` does not need to be on your PATH. To run
+commands by hand instead, activate the venv first:
+`source testbed/.venv/bin/activate`.
 
 ## Run
 
 ```bash
-# 1. Start the bridge (headless)
+# 1. Start the bridge (headless; keep it running in its own terminal)
 scripts/run_bridge.sh            # ws://127.0.0.1:8765
 
 # 2. Run the demo — default `auto` tries the LLM, then hands off to the
 #    scripted agent so the run always completes
-python -m testbed.demo --agent auto
+scripts/run_demo.sh --agent auto
 
 #   scripted only (deterministic, no LLM needed)
-python -m testbed.demo --agent scripted
+scripts/run_demo.sh --agent scripted
 
 #   LLM only (any OpenAI-compatible endpoint; ollama by default)
-python -m testbed.demo --agent llm --model gemma4:e2b
-python -m testbed.demo --agent llm \
+scripts/run_demo.sh --agent llm --model gemma4:e2b
+scripts/run_demo.sh --agent llm \
     --base-url https://api.openai.com/v1 --model gpt-4o-mini --api-key $OPENAI_API_KEY
 ```
 
+If the bridge is already running, `run_bridge.sh` will say so (the port is
+taken); stop the old one with `fuser -k 8765/tcp` or Ctrl-C in its terminal.
+
 The demo prints a full transcript of tool calls/results to stdout and saves the
 capsule's final first-person frame to `demo_final_frame.png`.
 
 ## Conformance
 
 ```bash
-python -m testbed.conformance ~/Desktop/aicc-spec/conformance/scenarios
+testbed/.venv/bin/python -m testbed.conformance ~/Desktop/aicc-spec/conformance/scenarios
 # [PASS] core-01..core-09  ->  9/9 scenarios passed
 ```
 
@@ -112,5 +117,5 @@ asynchronously when `move` hits a wall or crate.
 ## Tests
 
 ```bash
-python -m pytest -q        # 33 tests: physics, renderer, tools, protocol
+testbed/.venv/bin/python -m pytest -q   # 33 tests: physics, renderer, tools, protocol
 ```