docs(sample): document band sample run in README and AGENTS.md

AGENTS.md

@@ -362,6 +362,24 @@ For full flag/argument reference, use `band <command> --help`. This section cove
   - `complete_no_number` — resources created but no number was available in the requested area code; re-run with `--area-code` to try a different code.
   - `partial` — quickstart stopped after a failure but printed the resource IDs it created so far (app, VCP, sub-account, location, and possibly an ordered phone number). Re-running reuses the app/VCP/sub-account/location via idempotency checks. **Caveat:** if a number was ordered but its VCP assignment failed, the number is printed under `phoneNumber` but is NOT auto-reassigned on re-run (a re-run would order a *new* number) — finish the existing one with `band vcp assign <vcp-id> <phoneNumber>`.
 
+### Samples
+
+- **`band sample run` is helpful for demoing what a developer can accomplish with Bandwidth.** It clones a repo, starts a local process, launches ngrok, and blocks for the lifetime of the app. If you need to deploy a sample for a user, use the step-by-step [Agent Workflows](#agent-workflows) for the underlying provisioning.
+- **`band sample list` is safe for discovery.** Run it to enumerate available samples and supported languages before telling a user which command to run.
+- **Credentials are auto-wired.** `band sample run` reads the active band profile and writes `BW_ACCOUNT_ID`, `BW_CLIENT_ID`, and `BW_CLIENT_SECRET` to a `.env` file in the clone directory — the user never needs to copy credentials manually. Extra credentials (like `OPENAI_API_KEY` for the `live-assistant` sample) must be supplied via CLI flags or set as environment variables beforehand.
+- **The `live-assistant` sample is the primary voice AI demo.** It pairs Bandwidth's PSTN infrastructure (dialing, audio streaming, webhook routing) with the OpenAI Realtime API. The command to give a user:
+
+  ```bash
+  band sample run live-assistant \
+    --language python \
+    --openai-key sk-... \
+    --call-to +15559876543
+  ```
+
+  Prerequisites the user needs: ngrok (`brew install ngrok/ngrok/ngrok`), Python 3.11+, and an OpenAI API key with Realtime API access. A Bandwidth Build trial account is sufficient — no full account required.
+
+- **Voice application and phone number are resolved automatically.** `band sample run` calls `band app list` internally and creates (or reuses) a voice application named `band-sample-<name>`. It picks the first in-service phone number on the account. No manual provisioning needed before running the sample.
+
 ---
 
 ## Timeout Recovery

README.md

@@ -575,6 +575,13 @@ All five share the same filters: `--to`/`--from` (comma-separated E.164), `--dir
 | `band portin bulk get-tns <id>` | Poll the asynchronous TN-list validation |
 | `band portin bulk get <id>` / `bulk list` | Inspect bulk orders |
 
+### Samples
+
+| Command | What it does |
+|---------|-------------|
+| `band sample list` | List available sample applications and their supported languages |
+| `band sample run <name>` | Clone, configure, and launch a sample app with your credentials auto-wired |
+
 ### Other
 
 | Command | What it does |
@@ -689,6 +696,46 @@ For the full agent reference — dependency chains, provisioning workflows, erro
 
 ---
 
+## Sample applications
+
+Want to see Bandwidth in action without writing any boilerplate? The CLI ships with a samples catalog — runnable apps that clone, configure, and launch with a single command.
+
+```sh
+band sample list                 # see what's available
+band sample run live-assistant --language python --openai-key sk-...
+```
+
+`band sample run` handles everything: clones the GitHub repo, creates a virtual environment, installs dependencies, starts an ngrok tunnel, wires your Bandwidth credentials into a `.env` file, creates or reuses a voice application, and launches the app. Pass `--call-to` and it dials a number automatically once the app is healthy.
+
+### Try the OpenAI live assistant
+
+The flagship sample is a real-time AI voice assistant powered by the OpenAI Realtime API. It's the fastest way to see what Bandwidth's infrastructure can do: Bandwidth owns the PSTN layer — dialing, audio streaming, and webhook routing — while your AI provider handles the intelligence. You supply the API key; Bandwidth supplies the phone network.
+
+```sh
+band sample run live-assistant \
+  --language python \
+  --openai-key sk-... \
+  --call-to +15559876543
+```
+
+**Prerequisites:**
+- ngrok installed (`brew install ngrok/ngrok/ngrok`)
+- Python 3.11+
+- An OpenAI API key with Realtime API access
+- A Bandwidth account with at least one phone number (Bandwidth Build trial accounts work)
+
+**What happens when you run it:**
+1. The sample app clones from [bandwidth-samples/openai-live-websockets-python](https://github.com/Bandwidth-Samples/openai-live-websockets-python) to `~/.band/samples/`
+2. ngrok starts a tunnel on port 3000 and the CLI picks up the public URL
+3. Your Bandwidth credentials (`BW_ACCOUNT_ID`, `BW_CLIENT_ID`, `BW_CLIENT_SECRET`) are written to a `.env` file — no manual copy-paste
+4. A voice application is created (or reused if one already exists) with the ngrok URL as the callback
+5. The Python app starts and is ready to accept calls
+6. If you passed `--call-to`, the CLI dials that number as soon as the health check passes — answer and talk to the assistant
+
+**Want to transfer calls?** Pass `--transfer-to +1XXXXXXXXXX` to give the assistant a number to hand callers off to.
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, CI details, and guidelines.