diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f99a84..3c569d2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,3 +5,11 @@ All notable changes to this project are documented here. The format is based on
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+
+### Documentation
+
+- **README rewrite** — refreshed the top-level README (example table, prerequisites, root
+ scripts, footer) and fixed the API-key URL in `mcp-server-setup/README.md`, which still
+ pointed at the retired `wave.online/settings/api-keys` path instead of
+ `wave.online/developers`. Also tightened the banner wording so it no longer implies the
+ README-only `getting-started` and `mcp/claude-config` directories are clone-and-run projects.
diff --git a/README.md b/README.md
index 58ce4b1..22207c8 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,55 @@
-# WAVE examples
+
-Working examples for the WAVE developer platform. Each directory is a standalone project you can clone and run.
+# examples
+
+**Working, runnable examples for the WAVE developer platform — the SDK, the ADK, and the MCP server. Each standalone example directory is a project you can clone and run; get-started guides live in the table below.**
+
+    
+
+[wave.online](https://wave.online) · [Docs](https://docs.wave.online) · [github](https://github.com/wave-av/examples)
+
+
+
+---
## Examples
| Example | Package | Description |
-|---------|---------|-------------|
+| --- | --- | --- |
| [`sdk-quickstart`](./sdk-quickstart) | [`@wave-av/sdk`](https://github.com/wave-av/sdk) | Create a stream, start it, and fetch viewer analytics |
-| [`mcp-server-setup`](./mcp-server-setup) | [`@wave-av/mcp-server`](https://github.com/wave-av/mcp-server) | Configure WAVE tools in Claude, Cursor, or any MCP client |
| [`adk-hello-agent`](./adk-hello-agent) | [`@wave-av/adk`](https://github.com/wave-av/adk) | Build an AI agent that monitors stream quality |
+| [`mcp-server-setup`](./mcp-server-setup) | [`@wave-av/mcp-server`](https://github.com/wave-av/mcp-server) | Configure WAVE tools in Claude, Cursor, or any MCP client |
+| [`getting-started`](./getting-started) | `@wave-av/sdk` | Walkthrough: your first live stream in under 5 minutes |
+| [`mcp/claude-config`](./mcp/claude-config) | `@wave-av/mcp-server` | `.mcp.json` snippet for Claude Code / Cursor / Windsurf |
## Prerequisites
- Node.js 18+
-- A WAVE API key ([get one here](https://wave.online/settings/api-keys))
+- A WAVE API key ([get one here](https://wave.online/developers))
## Getting started
```bash
-# Clone this repo
git clone https://github.com/wave-av/examples.git
cd examples
-# Pick an example
+# Pick a runnable example (has its own package.json)
cd sdk-quickstart
pnpm install
pnpm start
```
+The repo root also has two npm scripts wired to lighter-weight snippets:
+
+```bash
+pnpm run basic-stream # runs sdk/basic-stream/index.ts
+pnpm run stream-monitor # runs adk/stream-monitor/index.ts
+```
+
## Get help
- [Documentation](https://docs.wave.online)
- [SDK reference](https://github.com/wave-av/sdk)
-- [Discussions](https://github.com/orgs/wave-av/discussions)
## License
@@ -41,4 +58,4 @@ pnpm start
---
-wave.online · Docs · Developers · For agents
+wave.online · Docs · Developers
diff --git a/mcp-server-setup/README.md b/mcp-server-setup/README.md
index ad4b4cd..e5375d6 100644
--- a/mcp-server-setup/README.md
+++ b/mcp-server-setup/README.md
@@ -4,7 +4,7 @@ Configure the WAVE MCP server so your AI coding assistant can manage streams, pr
## 1. Get an API key
-Create one at [wave.online/settings/api-keys](https://wave.online/settings/api-keys), or via CLI:
+Create one at [wave.online/developers](https://wave.online/developers), or via CLI:
```bash
npx @wave-av/sdk auth login