diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5037045..e7749cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -128,6 +128,14 @@ All notable changes to this project are documented here. The format is based on
- **`capabilities.json`** — registers this repository with the organization's platform
registry for discovery and lifecycle tracking. (#3)
+### Documentation
+
+- **docs: rewrite README** — restructured the top-level README (badges, quick start, repo
+ layout, related-packages table) and refreshed it against the current spec: clarified that
+ the x402-payable render operations (`renderVideo`, `renderPoll`, `renderEvents`) and the
+ device-authorization-flow responses are exceptions to the shared Bearer-token/`Error`-envelope
+ shape, and fixed the error-envelope example to match the `Error` schema's actual field types
+ (`details` is an object, `suggestions`/`did_you_mean` are arrays, not strings).
### Changed
- **License: Apache-2.0** — the specification and repository now carry the Apache-2.0
diff --git a/README.md b/README.md
index 175442c..397dca7 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,89 @@
-# WAVE API specification
+# api-spec
-WAVE is media infrastructure for the agentic internet: one call shape moves live and on-demand media across every transport, and both kinds of user, people and agents, discover it, call it, and pay for it per call. This repository is the OpenAPI 3.1 specification for that call shape.
+
-## Overview
+**WAVE is media infrastructure for the agentic internet: one call shape moves live and on-demand
+media across every transport, and both kinds of user, people and agents, discover it, call it, and
+pay for it per call.** This repository is the OpenAPI 3.1 specification for that call shape — 229
+documented endpoint paths across 181 tag groups (streaming, production, analytics, voice, captions,
+clips, and more), plus generators for client SDKs.
-Complete API specification covering 34 API modules: streaming, production, analytics, voice, captions, chapters, clips, phone, collaboration, search, and more.
+    
-## Usage
+[wave.online](https://wave.online) · [Docs](https://docs.wave.online) · [GitHub](https://github.com/wave-av/api-spec) · [Status](https://wave.online/status)
+
+
+
+---
+
+## What this is
+
+A single-file OpenAPI 3.1 document (`openapi.yaml`) describing the WAVE Enterprise Streaming Platform
+API: 229 endpoint paths grouped under 181 tags. It is the source of truth other WAVE packages generate
+from — the [`@wave-av/sdk`](https://www.npmjs.com/package/@wave-av/sdk) TypeScript client is built from
+this spec.
+
+## Quick start
```bash
-# Preview with Redoc
+# Preview the spec in a browser (Redoc)
npx @redocly/cli preview openapi.yaml
-# Validate
+# Lint / validate
npx @redocly/cli lint openapi.yaml
-# Generate SDKs
+# Generate a client SDK (example: TypeScript fetch client)
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sdk/typescript
```
## Authentication
-All API requests require a Bearer token:
+Most documented endpoints require a Bearer token (the x402-payable `/render` operations —
+`renderVideo`, `renderPoll`, `renderEvents` — are the exception; they set `security: []` and
+authenticate via an x402 payment challenge instead):
```
Authorization: Bearer YOUR_API_KEY
```
-Get your API key at [wave.online/developers](https://wave.online/developers).
+## Errors
+
+The spec documents a normalized error envelope used across most endpoints (the x402 payment-challenge
+and device-authorization-flow responses use their own distinct shapes, noted above and in the spec
+itself):
+
+```json
+{ "error": { "code": "...", "message": "...", "details": { "field": "..." }, "suggestions": ["..."], "did_you_mean": ["..."], "doc_url": "..." } }
+```
-## Related
+List endpoints support `page` / `perPage` pagination, and requests are subject to rate limiting
+(responses include a `Retry-After` header when throttled) — both per the spec's top-level description.
-- [@wave-av/sdk](https://www.npmjs.com/package/@wave-av/sdk) — TypeScript SDK (34 API modules)
-- [@wave-av/adk](https://www.npmjs.com/package/@wave-av/adk) — Agent Developer Kit
-- [@wave-av/mcp-server](https://www.npmjs.com/package/@wave-av/mcp-server) — MCP server for AI tools
-- [@wave-av/cli](https://www.npmjs.com/package/@wave-av/cli) — Command-line interface
+## Repo layout
+
+| Path | What it is |
+| --- | --- |
+| `openapi.yaml` | The spec itself — 14,039 lines, 229 paths, 181 tags |
+| `capabilities.json` | Machine-readable lifecycle metadata (this spec is tagged `ga`, version 3.0.0) |
+| `scripts/public-repo-guard` | CI check that keeps this public mirror free of internal-only content |
+
+## Related packages
+
+| Package | Description |
+| --- | --- |
+| [@wave-av/sdk](https://www.npmjs.com/package/@wave-av/sdk) | TypeScript SDK generated against this spec |
+| [@wave-av/adk](https://www.npmjs.com/package/@wave-av/adk) | Agent Developer Kit |
+| [@wave-av/mcp-server](https://www.npmjs.com/package/@wave-av/mcp-server) | MCP server exposing WAVE APIs as tools |
+| [@wave-av/cli](https://www.npmjs.com/package/@wave-av/cli) | Command-line interface |
## License
Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+---
+
+
+
+**Built by [WAVE Online, LLC](https://wave.online)** · [wave.online](https://wave.online) · [Docs](https://docs.wave.online)
+
+